localhost1978/localhost/LOCALHOST1978/SSK_DocGen - Storage Bucket

SSK_DocGen

Status: P0 and P1 source and configuration are implemented. Manual Xcode verification is not run.

See SSK_DocGen Phase and Priority Roadmap for the complete phase matrix, priority specifications, and capability roadmap.

---

1. Module Role and Topology

SSK_DocGen is the private documentation generator and resource worker for SovereignSurvivalKit. It is not the external Xcode MCP entry point.

Xcode has one external MCP entry point:

SSK_StorageHost acp-agent

The request path is:

Xcode or Approved MCP Client
  │ (stdio)
  ▼
SSK_StorageHost acp-agent (External MCP Facade)
  │ (com.ssk.vaulthost Mach XPC)
  ▼
SSKVaultHost Daemon (Validates Audit Token & Code Signature)
  │ (Private Worker Process)
  ▼
SSK_DocGen (Isolated Resource Worker)
  │ (Descriptor-Relative Read)
  ▼
Approved Documentation Ledger (SSK_Ledger_Vault)

The commerce tools in SSK_StorageHost acp-agent remain unchanged. DocGen adds documentation resources and maintenance tools.

---

2. P0 and P1 User Capabilities

An approved local MCP client can discover and read documentation resources:

Resource	Logical URI	MIME Type
DocC Index	ssk://spec:SSK-DocGen-P0/ledger/documentation/docc-index	application/json
Codebase Graph	ssk://spec:SSK-DocGen-P0/ledger/documentation/codebase-graph	application/json
Documentation Index	ssk://spec:SSK-DocGen-P0/ledger/documentation/master-index	text/markdown
Refresh Status	ssk://spec:SSK-DocGen-P1/ledger/documentation/status	application/json

P1 adds documentation refresh and status query tools to SSK_StorageHost acp-agent:

• refresh_docs: Triggers background documentation rescanning and updates the ledger in isolated staging.
• get_docgen_status: Returns current state (queued, running, ready, or failed) and process metrics.

The client does not provide a file path, executable path, workspace path, or vault path. SSKVaultHost stores operator-approved roots in secure configuration. The daemon reads this configuration and starts the private worker.

---

3. Phase Summary

Phase	Priority Level	User Capability	Status
P0	Critical	Read approved local documentation resources via SSK_StorageHost acp-agent.	Implemented, not verified
P1	High	Request local documentation refresh and query status.	Implemented, not verified
P2	Medium	Review proposed documentation changes and approve or reject before publication.	Planned. Not available in P1.
P3	Low	Read approved documentation from enrolled peer mesh devices.	Planned. Not available in P1.

---

4. Xcode Setup

Use the SSKVaultHost scheme to prepare the local daemon:

1. Create an isolated workspace directory and an isolated vault directory.
2. In the SSKVaultHost Run scheme, set SSK_DOCGEN_WORKSPACE to the absolute workspace directory.
3. Set SSK_DOCGEN_VAULT to the absolute vault directory.
4. Build and run SSKVaultHost.
5. Confirm that the application contains SSK_StorageHost, SSK_DocGen, and Contents/Library/LaunchAgents/com.ssk.vaulthost.plist.
6. Confirm that the launch agent is registered or approve it when macOS requests permission.
7. Build and install XCPSSKPlugin, or use /usr/local/bin/SSK_StorageHost.
8. Configure the MCP command in Xcode as SSK_StorageHost acp-agent.

Do not configure Xcode to start SSK_DocGen serve directly.

See SSK_DocGen_Manual_Testing_Guide.md for the complete manual procedure.

---

5. Private Worker Commands

SSK_DocGen provides two internal engineering commands:

SSK_DocGen generate --vault <path> [--workspace <path>] [--clean|--no-clean]
SSK_DocGen serve [--vault <path>] [--workspace <path>]

• generate builds ledger artifacts. It requires --vault. Do not use a shared or production vault for a test.
• serve is a private worker protocol mode. The host starts it with trusted configuration. It receives JSON-RPC requests on standard input and writes protocol responses to standard output. Diagnostics go to standard error.

---

6. Security Boundaries

• SSK_StorageHost acp-agent owns MCP standard input and standard output.
• The MCP facade accepts only fixed logical DocGen URIs.
• The named XPC route uses typed, versioned DocGenHostCommand messages.
• The XPC listener verifies the audit token and Apple code signature before exporting the service.
• SSKVaultHost persists approved roots in an owner-only directory and configuration file.
• The daemon resolves approved roots and the bundled worker. Clients cannot select them.
• Child-process input, output, diagnostics, duration, and response counts are bounded.
• The resource reader uses descriptor-relative access, no-symlink checks, regular-file checks, and bounded reads.
• Content is redacted in the worker and again at the external MCP boundary.
• Errors never return local file paths, private keys, claims, or credentials.

---

7. Development and Testing Rules

• Use SSK_DocGenTests for private worker and resource-reader tests.
• Use SSK_AbstractionsTests for typed resource and command model tests.
• Use SSK_FoundationTests for process launcher and XPC route tests.
• Use SSK_ProvidersTests for secure configuration store and MCP facade tests.
• Use SSKVaultHost and XCPSSKPlugin schemes for bundle and lifecycle checks.
• Do not claim that an Xcode test passed without the attached Xcode result.
• Do not add a second Xcode agent, daemon, Mach service, or DocGen network server.
• Do not make SSK_Providers import SSK_Orchestrator.
• Do not use git. This workspace uses lore for version control.