Skip to content

[runtime] align docs with implemented runtime surface#18

Merged
GsCommand merged 1 commit intomainfrom
codex/audit-and-rewrite-commandlayer-documentation
Mar 20, 2026
Merged

[runtime] align docs with implemented runtime surface#18
GsCommand merged 1 commit intomainfrom
codex/audit-and-rewrite-commandlayer-documentation

Conversation

@GsCommand
Copy link
Copy Markdown
Contributor

Motivation

  • Ensure repository documentation matches the actual implementation in server.mjs, scripts, tests, and workflows rather than describing aspirational or legacy behavior.
  • Remove or reclassify stale claims about routes, environment variables, and operational controls that the code does not implement.
  • Present a clear operator/dev interface (routes, env names, debug gating, ENS verification, signing model) that a skeptical engineer can verify by reading the code and running local checks.

Description

  • Rewrote README.md, docs/CONFIGURATION.md, docs/OPERATIONS.md, and SECURITY.md to reflect the exact routes, env vars, verification semantics, debug gating, SSRF/CORS behavior, schema warmup behavior, and signing model implemented in server.mjs (no application code changes).
  • Updated agent/automation manifests AGENTS.md and CLAUDE.md to stop referencing repo-external setup scripts and stack-level commands, and to state the runtime health surface accurately (/health and /healthz).
  • Documented canonical env var names and exact precedence/aliases consumed by the server (private/public key sources, RECEIPT_SIGNER_ID, RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64, RECEIPT_SIGNING_PUBLIC_KEY_B64, DEV_AUTO_KEYS, ENABLE_DEBUG/DEBUG_TOKEN, ETH_RPC_URL, ENS_SIG_* keys, schema/validator knobs), and explicitly marked a set of env names and controls as not implemented (CORS envs, rate-limit envs, REQUEST_SCHEMA_VALIDATION, DEBUG_ROUTES_ENABLED/DEBUG_BEARER_TOKEN, VERIFIER_ENS_NAME, etc.).
  • Clarified verification behavior: production crypto uses @commandlayer/runtime-core, /verify accepts wrapped or bare receipts, supports ens=1, strict_kid=1, refresh=1, and schema=1, and may return 202 when VERIFY_SCHEMA_CACHED_ONLY=1 and validator is cold; legacy runtime/src/receipt-verification.js remains in-tree and is described as legacy/test compatibility only.

Testing

  • Ran static syntax check via npm run check and it completed successfully.
  • Ran the repository test suite via npm test, which runs unit tests and the smoke script; all tests passed (unit tests and smoke completed with no failures).
  • No application code was modified and the change set is documentation-only; tests were run to validate that the documentation aligns with observable repo behavior.

Codex Task

Why: bring public and agent-facing documentation into sync with the actual routes, env vars, verification path, and repo-local workflow.
Contract impact: none
@GsCommand GsCommand merged commit f16655b into main Mar 20, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant