docs: fix drift from compact header + arx3 across docs and skills

[baanish]

Audit of every doc/skill file against src/lib/payload/* after the compact-header refactor (1-char codec tag) and the arx3 codec, gated by two independent adversarial completeness reviews (an external Codex review of the diff + a multi-lens re-audit of the post-fix state). They found complementary, non-overlapping residuals — all incorporated. Doc/comment changes only; no code or behavior changes.

1. "The compact tag encodes the active dictionary version" — false

The biggest drift, recurring across 5 docs and 2 source doc-comments. Per src/lib/payload/fragment-arx.ts:35-44, the compact a/b/c tags do not carry a dictionary version — they imply the build's current pinned dictionary, and the build refuses to decode a newer one. Corrected in AGENTS.md, docs/url-fragments.md, docs/payload-format.md, docs/architecture.md, skills/agent-render-linking/SKILL.md, and the comments in schema.ts (the compactCodecTags header) and arx-codec.ts that seeded the myth.

2. arx3 missing from codec enumerations

arx3 is shipped and first in DEFAULT_ASYNC_CODEC_PRIORITY (fragment.ts:35). Added it to the codec/tag lists, the arx-codec.ts/bench-codecs.mjs descriptions, and added the missing public/arx2-dictionary.json.br key-files entry in AGENTS.md.

3. Stale legacy/example placeholders

• The generic legacy template v1.<codec>.<dictVersion>.<payload> is only accurate for the arx-family; non-arx legacy links are v1.<codec>.<payload>. Corrected in AGENTS.md, docs/payload-format.md, and both skills.
• The agent-render-linking skill's chat examples used the legacy #agent-render=... placeholder, contradicting the skill's own rule to always build the compact form. Switched to #<tag><payload>.

4. Accuracy corrections (verified against code)

• baseBMP density: ~55% → ~60% fewer chars than base76 (base76 ≈ 6.27 bits/char vs baseBMP ≈ 15.92 per arx-codec.ts). Updated in the docs and the arxCompressBMP doc-comment so source and docs agree.
• selfhosted skill: "envelope validation" → the server only does a length/non-empty check (selfhosted/validate.ts); full validation is client-side.
• arx3 wire selection: the skill now matches buildArx3Candidates (generate all four wires, measure baseBMP by visible length, pick the shortest) instead of implying baseBMP is forced.
• docs/testing.md: listed 3 of 5 self-hosted tests and over-claimed the // @vitest-environment node pragma — added api-catalog.test.ts and static-headers.test.ts and scoped the pragma claim (api-catalog.test.ts runs in the default env and spawns the server).

Hygiene

Removed data/agent-render.db{,-shm,-wal} (self-hosted SQLite runtime state accidentally swept into the first commit by git add -A) and added a /data/*.db* ignore rule so it can't recur. (Caught by the Codex review.)

How this was found

Fan-out audit (one agent per doc) → perspective-diverse adversarial completeness pass → applied fixes → two more independent adversarial reviews of the result. The first pass missed the entire "tag encodes dictionary version" myth in payload-format.md/architecture.md; the post-fix reviews caught the surviving instances in schema.ts/arx-codec.ts comments, the incomplete testing.md test list, and the committed DB files.

Verification

lint (incl. check:public-export-docs), typecheck, and 236/236 unit tests pass. No test reads these doc files.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying agent-render with    Cloudflare Pages

Latest commit:	378a06e
Status:	✅  Deploy successful!
Preview URL:	https://672b31c4.agent-render.pages.dev
Branch Preview URL:	https://docs-fix-drift.agent-render.pages.dev

View logs

[greptile-apps]

Greptile Summary

This is a documentation-only audit PR that corrects three categories of drift between the codebase and its docs/skills after the compact-header refactor and arx3 codec addition. All changes were cross-checked against src/lib/payload/schema.ts and arx-codec.ts; no runtime behavior is altered.

• Dictionary-version myth removed: The false claim that the compact a/b/c tags encode a dictionary version is corrected in five files (AGENTS.md, docs/url-fragments.md, docs/payload-format.md, docs/architecture.md, skills/agent-render-linking/SKILL.md) to match schema.ts's actual inline comment.
• arx3 added throughout: arx3 and its c tag are added to every codec enumeration, the legacy-format description, and key-file list in AGENTS.md; the baseBMP density figure is corrected from ~55% to ~60% fewer chars than base76 (verified: 6.27 bits/char vs 15.92 bits/char).
• Stale placeholders fixed: Discord/Telegram/Slack examples in skills/agent-render-linking/SKILL.md are switched from the legacy #agent-render=... form to the compact #<tag><payload> form; the selfhosted skill frontmatter no longer overclaims full envelope validation.

Confidence Score: 5/5

Docs and skills only — no production code path is modified. All corrections were verified against the current source in schema.ts and arx-codec.ts.

Every changed claim was cross-checked against the referenced source symbols. The density math (6.27 bits/char base76, 15.92 bits/char baseBMP → ~60.6% fewer chars) is correct, the dictionary-version description now matches the schema.ts comment, arx3 is enumerated consistently, and the .gitignore preemption covers runtime SQLite files confirmed absent from HEAD. No logic, schemas, or tests are touched.

No files require special attention.

Important Files Changed

Filename	Overview
.gitignore	Adds /data/.db to ignore SQLite runtime files created by the self-hosted server; no db files exist in HEAD so this is purely preemptive.
AGENTS.md	Adds arx3 to codec lists, corrects the dictionary-version myth, fixes legacy format template, and adds the missing arx2-dictionary.json.br key-file entry.
docs/architecture.md	Corrects baseBMP density figure (~55% → ~60% fewer chars than base76, verified mathematically) and removes the false claim that the b tag encodes dictionary version.
docs/payload-format.md	Corrects the compact-tag description and arx/arx2 codec entries to remove the dictionary-version myth; fixes legacy format template for non-arx codecs.
docs/testing.md	Adds api-catalog.test.ts and static-headers.test.ts to the self-hosted test suite documentation and clarifies the @vitest-environment node scoping.
docs/url-fragments.md	Removes the false 'tag also encodes the active dictionary version' sentence; adds a note that only the legacy header carries an explicit version.
skills/agent-render-linking/SKILL.md	Fixes dictionary-version myth, updates legacy format template, corrects arx3 wire-shape selection description, and switches Discord/Telegram/Slack examples from the legacy #agent-render=... placeholder to the correct compact # form.
skills/selfhosted-agent-render/SKILL.md	Corrects frontmatter claim about 'same envelope validation' to accurately reflect that the server only performs a length/non-empty check and full validation is client-side.
src/lib/payload/arx-codec.ts	Updates arxCompressBMP JSDoc to correct the baseBMP-vs-base76 density figure from ~55% to ~60%, consistent with the documented bit-rates.
src/lib/payload/schema.ts	Corrects the inline comment on compact codec tags to accurately state the tag encodes the codec only and does not carry a dictionary version.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["URL fragment #<tag><payload>"] --> B{tag char}
    B -->|p| C[plain — base64url JSON]
    B -->|l| D[lz — lz-string compressed]
    B -->|d| E[deflate — deflate + base64url]
    B -->|a| F[arx — dict subst + brotli + wire encoding]
    B -->|b| G[arx2 — tuple envelope + overlay dict + arx stack]
    B -->|c| H[arx3 — same as arx2, baseBMP wins on visible length]
    F --> I["Tag implies build-pinned dict\n(does NOT carry dictVersion)"]
    G --> I
    H --> I
    J["Legacy: #agent-render=v1.<codec>.<payload>\narx-family: ...v1.arx.<dictVersion>.<payload>"] -->|still decodes| B

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["URL fragment #<tag><payload>"] --> B{tag char}
    B -->|p| C[plain — base64url JSON]
    B -->|l| D[lz — lz-string compressed]
    B -->|d| E[deflate — deflate + base64url]
    B -->|a| F[arx — dict subst + brotli + wire encoding]
    B -->|b| G[arx2 — tuple envelope + overlay dict + arx stack]
    B -->|c| H[arx3 — same as arx2, baseBMP wins on visible length]
    F --> I["Tag implies build-pinned dict\n(does NOT carry dictVersion)"]
    G --> I
    H --> I
    J["Legacy: #agent-render=v1.<codec>.<payload>\narx-family: ...v1.arx.<dictVersion>.<payload>"] -->|still decodes| B

Loading

_{Reviews (2): Last reviewed commit: "docs: fix drift from compact header + ar..." | Re-trigger Greptile}

[coderabbitai]

Warning

Review limit reached

@baanish, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 26 minutes and 15 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 57f9286a-67d4-4b08-8474-e5135dcaf53c

📥 Commits

Reviewing files that changed from the base of the PR and between d1a0e22 and 378a06e.

📒 Files selected for processing (10)

• .gitignore
• AGENTS.md
• docs/architecture.md
• docs/payload-format.md
• docs/testing.md
• docs/url-fragments.md
• skills/agent-render-linking/SKILL.md
• skills/selfhosted-agent-render/SKILL.md
• src/lib/payload/arx-codec.ts
• src/lib/payload/schema.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/fix-drift

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

agent-render/data/agent-render.db

Line 1 in 9aa9f0d

SQLite format 3���@ ���.�� �

Remove the seeded runtime database from the repo

This commit adds the default self-hosted SQLite store (data/agent-render.db, plus WAL/SHM files) with an artifacts row already present; since selfhosted/db.ts defaults DB_PATH to ./data/agent-render.db, anyone running npm run selfhosted:dev from a checkout starts from committed mutable state and can serve/delete that stale test artifact instead of an empty fresh database. Please remove these runtime files and ignore data/.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

All 10 changed files reviewed. This is a docs/comments-only PR — the only source touches are doc-comment text in src/lib/payload/arx-codec.ts and src/lib/payload/schema.ts (no code or behavior changes).

Each corrected claim was verified against the actual source:

• Compact tag does not carry a dictionary version — fragment-arx.ts:35-60: tags a/b/c imply the build's pinned dictionary; EXPECTED_ARX_DICTIONARY_VERSION = 1, and the build refuses a newer one. The schema.ts comment now matches.
• arx3 (c) added and first in DEFAULT_ASYNC_CODEC_PRIORITY (fragment.ts:35) and compactCodecTags (schema.ts:18-25).
• Legacy template corrected — non-arx is v1.<codec>.<payload>; arx-family carry an extra <dictVersion>. segment. Matches fragment.ts:333 and fragment-arx.ts:120-130.
• baseBMP density ~60% vs base76 (was ~55%) — math holds: 1 − 6.27/15.92 ≈ 60.6%; bits/char figures match arx-codec.ts:638,839,1343.
• arx3 wire selection — buildArx3Candidates (fragment-arx.ts:236-261) generates all four wires and budgets baseBMP by visible length (value.length) while others use transport length, then picks the min.
• selfhosted validation — validate.ts performs only a length/non-empty check; its own comment states full envelope validation is client-side.
• testing.md — api-catalog.test.ts has no @vitest-environment node pragma and spawns a child process; the other 4 selfhosted tests do use it (4 of 5).
• public/arx2-dictionary.json.br exists, so the new AGENTS.md key file entry is valid; .gitignore /data/*.db* matches the default ./data/agent-render.db (db.ts:31).

Note: the SQLite runtime files (data/agent-render.db{,-shm,-wal}) previously flagged by Greptile are no longer in the diff — the latest commit removed them and added the ignore rule, so that concern is resolved.

Files Reviewed (10 files)

• .gitignore
• AGENTS.md
• docs/architecture.md
• docs/payload-format.md
• docs/testing.md
• docs/url-fragments.md
• skills/agent-render-linking/SKILL.md
• skills/selfhosted-agent-render/SKILL.md
• src/lib/payload/arx-codec.ts
• src/lib/payload/schema.ts

---

_{Reviewed by GLM-5.2 · Input: 183.3K · Output: 31K · Cached: 370.7K}