@foundocs/foundocs-setup 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# Foundocs setup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use the installation prompt from your project's Foundocs integration guide. It contains a ten-minute, one-use connection code, never an API key. The coding agent fixes an absolute project root and sends the prompt's JSON to the installer's **private stdin** using a process tool. Do not paste the JSON into shell command text, argv, logs, or a committed file.
+
+```text
+npx --yes @foundocs/foundocs-setup@0.1.0 install --root /absolute/project
+npx --yes @foundocs/foundocs-setup@0.1.0 doctor --root /absolute/project
+npx --yes @foundocs/foundocs-setup@0.1.0 rollback --root /absolute/project
+```
+
+The install command reads stdin until EOF. Commands never take codes or API keys as arguments. This package requires Node.js 22.19.0+ and a locally installed Claude Code or Codex CLI. Before exchanging the code it inspects the installed CLI's actual helper support, parses existing settings and checks private storage permissions. Missing or incompatible CLIs require installation/update or the manual guide. Codex's desktop app without its CLI cannot pass this automatic feature check.
+
+Input JSON follows `SetupInstallInput` version 1: `client` (`claude` or `codex`), `projectId`, `workspaceId`, `attemptId`, `code`, `exchangeUrl`, `mcpUrl`, and `version: 1`. The code is exchanged once for an installation key; same-attempt reruns reuse that private key. A newly issued attempt can replace a revoked key while retaining the previous key privately. Existing keys are never automatically revoked.
+
+Configuration is local to the exact `--root`: `steerdocs.json`, a marked `AGENTS.md` block, and either `.codex/config.toml` or `.mcp.json`. Claude additionally receives a marked `CLAUDE.md` reference to `AGENTS.md`. Existing instructions and foreign MCP entries are preserved. Conflicting project IDs, malformed files, symlinks, or a different same-name `steerdocs` server stop installation before exchanging the code. Resolve a conflict explicitly; this installer does not overwrite it.
+
+Keys, backups and installation journals live in `~/.local/share/steerdocs/setup`, outside the project. `STEERDOCS_SETUP_HOME` may select another absolute private directory outside the target project, including isolated test fixtures. Keep using that same value for doctor/rollback. Credentials are isolated by workspace, project, and canonical project root. Durable authentication helpers are copied there; MCP settings use the absolute Node executable and these helpers, independent of npm cache lifetime. Claude Code uses its HTTP `headersHelper`. Codex 0.149.1 reserves `Authorization` in its HTTP helper, so Codex uses a bundled local stdio adapter that forwards MCP tool discovery and calls to the same Remote HTTP endpoint with the saved Bearer key. This adapter preserves remote schemas, annotations, structured results and errors, and requires an explicit valid project ID on every call. A changed valid project ID is forwarded unchanged; the remote server enforces workspace access. It adds no remote service. macOS/Linux use user-only directories/files (0700/0600). Windows uses PowerShell to apply and verify a protected current-user-only ACL; unsupported ACL filesystems stop before code exchange.
+
+The helper prefers the saved installation credential. To explicitly use a process-provided `STEERDOCS_API_KEY`, also provide matching `STEERDOCS_PROJECT_ID` and `STEERDOCS_WORKSPACE_ID`. An unrelated shell key never silently overrides the saved workspace key. The helper's stdout contains authentication headers solely for the host MCP client; do not invoke it through tools that log stdout.
+
+Doctor performs MCP initialize, tool discovery, and `get_project_context` with the exact project ID. `diagnostic_passed` means the independent diagnostic succeeded. You must still trust/reconnect the project in the selected host and call its MCP tool to verify that host. Setup never reports host connection from file creation alone.
+
+For response loss or failure before private key storage, the error reports the attempt ID and guide recovery route: inspect/revoke only that attempt's issued key and generate a new code. After key storage, rerun the same installation input. `rollback` restores only files still matching the installer-written content; concurrent edits are retained and reported. It preserves private credentials for retry. A stale operation lock after process interruption is never automatically deleted: confirm no installer is running before removing the reported private lock file.
+
+## Verification status
+
+The implementation includes unit/integration tests for both configuration formats, preservation, reruns, conflicts, credential isolation, redaction, recovery, rollback, protocol diagnostics, path quoting and ACL command generation. Local feature checks pass on macOS with Codex CLI 0.149.1 and Claude Code 2.1.284. Windows/Linux command paths are implemented, but real runtime verification on those operating systems is still required before claiming them verified. Host tool invocation and registry installation evidence are recorded in the repository's remote-MCP review, separately from this package's tests.
+
+Development: `pnpm --filter @foundocs/foundocs-setup test` and `pnpm --filter @foundocs/foundocs-setup typecheck`.