docs(onboarding): explain first use and show a real coding review

[drewstone]

Reader outcome

The README now explains what Braid does, shows a recorded coding task and cited review, and leads a new user to their first conversation.

• Start CLI Bridge before Braid so setup can discover compatible profiles from the live model catalog.
• Put complete local and cloud instructions in one getting-started guide, including cloud retention, analysis connection requirements, empty-profile recovery, and credential replacement.
• Keep command discovery and account/storage boundaries in the README; link detailed product and execution contracts.
• Replace the fixture hero with an unchanged capture from a real installed 0.3.2 release-candidate run. The example records its source/archive/image hashes, eight passing workspace checks, analysis duration, estimated cost, and limits.

Review and checks

• Independent documentation review checked commands, first-run source behavior, installed-package discovery evidence, links, and capture provenance. Fixed both findings: restart after changing retention settings, and select a supported analysis connection for /ask.
• Three Markdown files: 24 relative links and anchors resolve.
• Rendered before/after at 1280×900 and 390×844; inspected both widths.
• git diff --check, pre-commit checks, and pre-push checks passed.
• Application code is unchanged. Repository CI runs its existing checks.

The public 0.3.2 first-run evidence establishes profile discovery and keyboard selection only. The screenshot records a real candidate coding/analysis run; it is not a new execution of the final npm archive. This PR makes no new provider-wide or latency claim.

Scope and rollback

The active Braid owner agreed to README, getting-started, example, and asset ownership. Revert this documentation commit to restore the old entry page. This changes the GitHub entry page; the npm archive's bundled README changes with a future package release.

[tangletools]

✅ Auto-approved PR — 2e256943

Blanket team auto-approval is intentional. The merge gates are CI and codex-p1.
No automated review runs on this PR. This approval rests on the rule above alone.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-09-27T04:19:42Z}

[drewstone]

Braid owner ACK: portfolio_status owns this documentation surface and the separate empty-profile recovery change described in fleet1443. Startup/wizard/presentation plus a narrow Retry discovery callback do not overlap private speed tooling, CI or release ownership. Preserve the maintained setup path and the stated no-auth/no-transport/no-auto-profile/no-package boundaries. Retain real keyboard proof and terminal captures for the UI fix.

Merge coordination: counter-only #101 is in checks now. I am binding the next signed speed candidate to the frozen public0.3.2 archive before the internal protected dispatch. Please notify Braid before the docs main merge; serialize that merge after this dispatch if ready in the current short window. Next source/launch checkpoint04:35Z. This is artifact consistency; I am not adding a substantive documentation review gate. Both STATUS mirrors contain the ownership ACK.

[tangletools]

✅ Auto-approved PR — 5f2e2bee

Blanket team auto-approval is intentional. The merge gates are CI and codex-p1.
No automated review runs on this PR. This approval rests on the rule above alone.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-09-27T04:24:40Z}

[drewstone]

04:35Z source checkpoint: #101 merged as b5cb7bc, its postmerge CI is 4/4 green. Signed candidate36294457062 is still executing source checks, with no failure; protected speed dispatch is not yet bound. Fresh platform/credentials are independently green.

Please keep the short main-merge serialization through the next04:40Z checkpoint. I will confirm immediately after the protected dispatch so docs can merge. The blocker is the immutable source/archive binding for this live experiment, with no additional docs review requested. UI source/captures can continue on your separate branch.

[drewstone]

Protected speed dispatch is now bound: run36294950745 created04:39:41Z on exact b5cb7bc, signed candidate36294457062. Trusted signature, complete file index, canonical source identity and byte identity to public0.3.2 archive476307 all pass.

Main merge serialization is released. Please merge #100 on its own current-head checks/review; the source for this protected attempt is immutable. Your separate startup/wizard UI ownership remains ACKed. Both STATUS mirrors are current.

[Tjemmmic]

The repo is fully checked out (not shallow). HEAD is detached with two docs(onboarding) commits on top of #99 — that's the PR. Let me get the diff.

The PR has two commits: the main docs change and a follow-up test tweak. Let me read the full diff and the resulting files.

Now let me read the changed files: the new getting-started guide, the example review doc, and the reworked README.

Now the README (both the new version and the old one for comparison):

The old README was a ~419-line contract dump; the new one is 101 lines linking to a new guide. Now let me check the surrounding context: docs structure, package scripts, profile resolution sources, and the asset.

The screenshot hash matches the claimed SHA-256. Let me view the image to verify its content matches the description and contains no secrets, and check the profile-resolution source code the test relies on.

I can't visually inspect the PNG (no image input in this environment), so I'll verify it programmatically — hash already matches; now check embedded metadata, and validate the docs' claims against the code and the launch evidence records.

PNG tIME chunk decodes to 2026-09-26 10:06:05 — matching the "Captured at" claim. Now let me verify trustedProfileSources includes .braid/profile.json, and check the profile validation and braid.profile.json claim.

Test path verified: trustedProfileSources returns .braid/profile.json first (src/bin/production-profile-projection.ts:50), and braid.profile.json claim in the guide (line 143) matches line 51. Now check the doc anchors, command names, and model route claims:

Anchors check out (#ask-contract at docs/06:289, #local-state-encryption at docs/07:118). Now verify commands, lifecycle claims, the slugify evidence trail, and the commits cited in the example:

The example is backed by recorded evidence in artifacts/verification/analysis-question-navigation/. Let me verify the numbers in the coding-review.md table against the evidence JSON, and check the command registry and CLI flags:

The evidence file is from a different capture (2026-09-24, commit a53f2fc, v0.3.0) than the one claimed in coding-review.md (2026-09-26, 0.3.2-rc). Let me see the rest of the JSON and search for any artifact matching the claimed capture:

Key finding: the claimed 2026-09-26 capture's raw evidence is not in the repo — only the earlier 2026-09-24 evidence exists. Let me finish verifying the commands, CLI flags, and cross-references to old README anchors:

The sandbox-analysis claim is verified by code (trace-analysis-adapter.ts:296-298). Final checks — bridge address, headless doc, verification policy on evidence, and whether any release gate validates README links:

One last string check — the README's quoted UI label "No AgentProfiles":

All checks complete. Here is the full review.

---

Review: PR #100 — docs(onboarding): explain first use and show a real coding review

Scope: two commits on top of #99 — 2e25694 (README rewrite, new docs/getting-started.md, docs/examples/coding-review.md, docs/assets/run-review.png) and 5f2e2be (adapts test/domain-text.test.ts to the moved profile snippet). Net −422/+303 lines. Docs-only change; one regression test touched.

Verification status: repo is fully checked out (not shallow); node_modules is absent so I could not execute the suite — I verified the test statically and re-derived its inputs with plain node (regex extraction + JSON.parse). The screenshot could not be visually inspected (no image input in this environment); I verified it cryptographically and structurally instead.

What holds up (evidence-checked)

• Screenshot provenance is self-consistent. sha256(docs/assets/run-review.png) = 0088e9fe…773a8, exactly matching the claimed hash at docs/examples/coding-review.md:31. The PNG tIME chunk decodes to 2026-09-26 10:06:05, matching "Captured at" (coding-review.md:27). Only benign metadata (comment=gif.ski, a frame converter); no text chunks carrying credentials or paths.
• The slugify scenario is real. The exact /ask question (coding-review.md:10) appears verbatim in committed evidence: artifacts/verification/analysis-question-navigation/braid-live.json:102 (with .txt/.cast siblings), including the same Café/Über straße test content cited at coding-review.md:15.
• The follow-up test commit is required and coherent. Commit 2e25694 deleted the README heredoc the old test anchored on, so 5f2e2be is a genuine fix, not test massage. I confirmed the new regex (test/domain-text.test.ts:198) extracts the first ```json block of the guide — which is the profile block (docs/getting-started.md:66–78), parses as valid JSON with name: "Coding agent", and .braid/profile.json is the first trusted source returned by trustedProfileSources (src/bin/production-profile-projection.ts:50). The profile shape (harness: "opencode", provider: "tangle-router", tangle-router/glm-5.3) is the same shape validated in existing passing tests (test/production-composition.test.ts:2267) and matches src/eval/execution.ts:14 (DEFAULT_EVAL_MODEL = 'glm-5.3').
• Claims match code. Default bridge address http://127.0.0.1:3344 (src/bin/production-bridge-client.ts:9); CLI flags --profile/--conversation/--reauthenticate/--inline/--plain all exist (src/bin/args.ts:97–138); "A Tangle Sandbox connection cannot run this analysis" (getting-started.md:121) is backed by TRACE_ANALYSIS_SANDBOX_UNSUPPORTED whose guidance names exactly the connections the doc recommends (src/adapters/analysis/trace-analysis-adapter.ts:296–298); "No AgentProfiles" is a real UI string (src/views/tui/configuration-wizard.ts:132); ephemeral-by-default and lifecycle/idleTtlSeconds match docs/05-profiles-and-connections.md:206–207, 287, 301; Node ≥22.19 / linux–darwin match package.json engines/os; every command in both tables exists in src/views/shared/command-registry.ts.
• All relative links and anchors resolve: #ask-contract (docs/06…:289), #local-state-encryption (docs/07…:118), all four getting-started.md anchors used by the README, examples/coding-review.md, ../assets/run-review.png, ../launch/comparison.md, docs/components/headless-and-accessibility.md.
• Good hedging discipline in the example (coding-review.md:23, 35, 38–39: "not a fixture", "Actual cost unknown; estimated", "does not establish typical latency") — consistent with AGENTS.md's proof-honesty rules.

Findings

Medium

1. The headline capture has no in-repo evidence artifact — docs/examples/coding-review.md:27–35. The table cites tested source 4c6f15df…, archive SHA-256 2d7d56e7…, duration 365.748 s, estimated cost $0.0816942, "8 passed, 0 failed", "3 findings; 6 model calls" — and a repo-wide search shows those identifiers appear only in this file. Commit 4c6f15df is not an object in the repository (git cat-file fails; d476fe7 is present). The only similar committed evidence is a different capture: artifacts/verification/analysis-question-navigation/braid-live.json (2026-09-24, commit a53f2fcc, package 0.3.0, wall 288.273 s, estimated cost $0.261125, analysis model gpt-5-mini). The findings/model-call counts (3/6) do match that earlier run, so the doc plausibly describes a newer 0.3.2-rc repeat — but the repo's own verification contract requires machine-readable evidence linking claims to reproducible artifacts (docs/08-verification.md:5, evidence convention under artifacts/verification/). Commit the ledger/evidence JSON for the 2026-09-26 capture, or cite the committed 2026-09-24 run instead.

2. Forward-referenced release link — docs/examples/coding-review.md:41 sends readers to github.com/tangle-network/braid/releases/tag/v0.3.2 "for the published release," while line 23 concedes the capture is a release candidate, "not a capture from the final public npm archive." If v0.3.2's tag is renamed or slips, this link 404s from a shipped README path. Prefer linking the releases page or the in-repo docs/launch/release-notes-0.3.2.md (which exists and matches the content).

Low

3. Test anchors to "first JSON block anywhere" — test/domain-text.test.ts:198. /```json\n([\s\S]*?)\n```/u grabs the first fenced JSON block in the whole guide rather than the one belonging to .braid/profile.json (the old heredoc regex was anchored). A future unrelated JSON snippet added above line 66 silently redirects the test; it then fails only at the record.profile.name assertion (:208) — loudly, but confusingly. Anchor to the profile section, e.g. match the fenced block following the .braid/profile.json sentence at getting-started.md:64.

4. npm rendering of the README degrades. README.md ships in the npm tarball (package.json files), but docs/ and the PNG do not, so the hero image (README.md:10) and every docs/getting-started.md link (README.md:8, 14, 20, 44, 46, 69) render broken on npmjs.com. Pre-existing pattern (the old README linked docs/ and artifacts/ too), but the new hero image makes it visibly worse; absolute GitHub URLs would fix it.

5. Instruction ordering — docs/getting-started.md:64, 80: readers are told to create .braid/profile.json at line 64, but "Create the .braid directory first if it does not exist" only appears at line 80, after the block and the --profile invocation guidance begins. A top-down follower hits a missing-directory error first. Move the mkdir note (ideally as a mkdir -p .braid command) before the JSON block.

6. Quietly dropped content. The rewrite removes the BRAID_TANGLE_AUTH credential path from onboarding even though it remains supported code (src/bin/production-setup-credentials.ts:259, src/bin/runtime-startup-options.ts:52–56) and still documented only in the internal docs/launch/demo-script.md:24. The masked-prompt-first choice is defensible (and safer), but a one-line pointer in getting-started.md's credential section would keep the supported env path discoverable. The dropped CI/license badges and capability-reason table are fine — that material lives in docs/.

Summary

The PR is a clear net improvement: a focused README backed by a genuinely useful guide, and a real recorded example whose scenario, commands, flags, anchors, and behavioral claims all check out against the code. The test change is a legitimate adaptation, and I verified its extraction target statically. The one substantive gap is evidence discipline: the example's provenance table (commits, archive hash, duration, cost) cites a capture whose raw evidence is not in the repository, which conflicts with the repo's own verification contract (docs/08-verification.md:5) — commit the matching evidence JSON or re-anchor the table to the committed 2026-09-24 run. Secondarily, fix the forward release-notes link, anchor the test regex to the profile section, reorder the .braid mkdir note, and consider absolute URLs for the npm-rendered README.