[akhileshthite]

Closes #164

The README now says what chel is, why it's useful, how to install it and get started, and where the rest of the docs are. The details moved into docs/:

• commands.md: every command and its options, including the ones the README never covered (upload, get, hash, verifySignature, version)
• server.md: what chel serve does, the dashboard, and running it in production
• configuration.md: chel.toml, environment variables, database backends and chelonia.json
• distributing.md: the release steps, build caching, the npm packages and Linux on musl

While moving them, I fixed what no longer matched the code: commands that don't exist (test, latestState, help <command>), the deploy/upload/pin usage, and the keygen and manifest formats. The Supported Platforms heading stays, since the launcher links to it. AGENTS.md, publish.ts and the drift test (now test/docs-defaults.test.ts) point to the new files.

Testing: I ran the README's getting-started steps for real from source, checked every link and anchor, and lint and the affected tests pass.

AI Usage: Claude Opus 5.5 xhigh
Self review: Approved

[akhileshthite]

/review

---

AI review started.

[github-actions]

Advanced AI Review

• Type: Agentic (crush)
• Model: glm-5.3

Click to expand review

Code Review

Base: origin/master (04e03b3)
Head: d03815f (HEAD)
Date: 2026-11-06
Model: glm-5.3

---

Reviewed the merged result against origin/master in two slices (README/AGENTS.md/test changes, and the new docs/ files), then verified every reported finding against the full diff and the source tree. The documentation was checked as code: command names, flags, aliases and defaults against src/*.ts builders and src/config-defaults.ts; the config precedence chain (env > flag > file > default) against the nconf store insertion order in src/parseConfig.ts:25-40; the list of config-validating commands against src/commands.test.ts; database backend options and defaults against src/serve/backend-schemas.ts and database-fs.ts; the release flow against package.json, scripts/publish.ts and scripts/binaries.ts; server/dashboard behavior against src/serve.ts and src/serve/; the platform table against package.json's optionalDependencies; the launcher exit codes 127/126 and the #supported-platforms anchor against bin/chel.js; and all cross-file links and anchors. The deleted test/readme-config.test.ts's coverage fully moved to test/docs-defaults.test.ts, and the README no longer contains a config example, so nothing it pinned is lost. Three issues found, none blocking.

1. 🟡 chel hash docs repeat a stale claim: .json files get no special treatment

• Addressed
• Dismissed

docs/commands.md:334-335 says:

Prints the content identifier (CID) of a file. The contents are read as raw
binary data, unless the file name ends in .json.

There is no .json special case anywhere in the code path. src/hash.ts:12-22 always uses the default multicodes.RAW, createEntryFromFile (src/utils.ts:15-19) always reads raw bytes and never dispatches on the file extension, and the CLI never passes a different multicode. test/hash.test.ts:29-40 explicitly pins this behavior: the step named "it should create a raw CID for a json file" asserts cid.code === multicodes.RAW for test/assets/hello.json. The "unless" clause describes a difference that does not exist; a reader will infer .json files are hashed differently (e.g. a JSON codec or normalized parsing), which is false. Since the PR's stated goal was to fix doc claims that no longer matched the code, this one should be dropped too:

## chel hash

chel hash

Prints the content identifier (CID) of a file, hashing its contents as raw
binary data.

Optionally, fix the source of the stale wording as well so it cannot be copied back into the docs — the sentence was copied verbatim from the yargs describe in src/hash.ts:35-36 ("File contents will be interpreted as raw binary data, unless the file extension is '.json'."), which is user-facing via chel hash --help:

  describe:
    'Computes and logs the content identifier (CID) for the given file.\n' +
    'File contents are hashed as raw binary data.',

(No behavioral change.)

2. ⚪ Rate-limit drift guard can pass on stale docs when values collide

• Addressed
• Dismissed

test/docs-defaults.test.ts:43-46 asserts only that each rate-limit default appears somewhere in backticks in docs/signup-and-billing.md:

for (const [window, value] of Object.entries(signup.limit)) {
  if (typeof value !== 'number') continue
  assertDocumented(doc, `the per-${window} rate limit default`, `\`${value}\``)
}

The check is not tied to the setting, so a changed default that equals any other number already in the document passes silently. Concretely: signup.limit is minute: 2, hour: 10, day: 50 (src/config-defaults.ts:28-33) and the doc says "(defaults `2`/`10`/`50` per IP)" (docs/signup-and-billing.md:22). If minute changed from 2 to 10 (or day from 50 to 10), that line would be quietly wrong while the test still passes, because the hour default's `10` satisfies the assertion. That is exactly the failure mode the file exists to prevent: a default changing without the documentation following. The other assertions in the file don't have this problem because their snippets include the setting name (maxFirstMessageBytes = 8192, `mem` (default), etc.).

Tying the three windows together, which still matches the current prose format, closes the hole:

assertDocumented(
  doc,
  'the per-window rate limit defaults',
  `\`${signup.limit.minute}\`/\`${signup.limit.hour}\`/\`${signup.limit.day}\``
)

3. ⚪ New test lines exceed the project's 100-column line width

• Addressed
• Dismissed

test/docs-defaults.test.ts:33-36 are 101, 114, 118 and 112 characters long, past the lineWidth: 100 configured in deno.json's fmt block (deno.json:84-89, which only excludes test/assets/) and documented in AGENTS.md. deno fmt would reflow them on the next run, creating unrelated diff noise, and the lint task (eslint ./src ./scripts) doesn't cover test/, so nothing in CI catches it. Wrapping, e.g.:

assertDocumented(
  config,
  'the example dashboard address',
  `dashboardListenIP = "${server.dashboardListenIP}"`
)

---

Review generated using glm-5.3 via Z.AI. Comment /review to re-run.

[taoeffect]

Instead of "Why chel" make the header "Features" and mention the dashboard.

Share a screenshot at the end of the section of the dashboard.