Revamp onboarding and unblock checkpoint validation

[hudsonaikins]

Teams can now reach the published local demo near the top of the README and find separate routes for repository integration, contribution, and protected operations. Contributors and agents share a short setup, scoped task, verification, recovery, and handoff workflow.

Changes

• Rebuild the README to 132 lines with actual installed-package output, explicit prerequisites, synthetic-data labels, capabilities, limits, existing branding, and a small architecture diagram.
• Add a documentation landing page with four routes. Move operator procedures into current guides and archive 13 completed ticket/review records without changing their identifiers, runtime paths, schemas, migrations, or manifest locations. Update nine manifest source links.
• Expand AGENTS.md to 77 lines and add one reusable contributor work-plan/handoff format. Existing manifests and durable validation/review records remain the authority.
• Activate the native PR template, retain its identical packaged counterpart, add native bug/feature forms, and refresh security guidance.
• Add dependency-free npm run docs:check to npm run check. GitHub Actions and Buildkite retain their existing required checks and now enforce documentation rules through the shared command.
• Preserve Apache-2.0. Describe Plane as legacy import support and make no AgentShift adapter or synthetic-performance claims.

Verification

• Public installation, version check, and demo passed in a clean macOS consumer directory (Node.js 26.3.1; PostgreSQL 14.15). Demo receipt: status: passed, cleanup: passed; Git/PostgreSQL real, provider/security records synthetic.
• Documentation checker and 13 focused tests passed, including broken links, wrong/unpinned installation versions, missing entries, template mismatches, size limits, and historical release versions.
• npm run check passed. The changed-code quality gate passed after the existing real PostgreSQL coverage suite and a focused coverage refresh for the simplified documentation checker.
• Existing package dry-run passed. GitHub's Markdown renderer was inspected for links, branding, actual receipt caption, and Mermaid markup.
• Source and packaged PR templates match. Issue forms parse correctly. Manifest source links resolve.
• The original checkout retains its 16 changes; its tracked diff is byte-for-byte unchanged.

Current review and validation gates

Current candidate: 1f0a2cf224b50c7575121af2144a98cbbbe93049.

The native checkpoint export now keeps every original commit and the original objects along selected metadata paths, omits unrelated trees and content, and compresses the pack for the existing two-part handoff. The observed bundle shrank from 191,502 to 60,663 bytes without changing native IDs or raising transport limits. The exporter applies the existing serialized privacy audit; preparation reports transport failures at the correct stage.

Focused tests passed (25 tests). Required shared checks, changed-code quality, dead-code checks, and package dry-run passed. Committed exact-head product validation passed on this candidate: decision.status: passed, totalCostUsd: 0, costTelemetryComplete: true (200.05 seconds). Its private receipt is /private/tmp/tabellio-harness-evidence/proof-fix-head-validation.json.

A clean local consumer imported the filtered pack through the existing CI loader, read checkpoint 4a06f28905d9 through pinned Entire 0.7.7, preserved native tip 9846c176f4e3426e24cea9c4f9818ed2af672f38, and passed owned cleanup. The runner variables were simulated locally; this is not hosted CI evidence.

All four required hosted checks passed on this exact candidate: Tests, Fallow changed-code, Package dry-run, and validate. Protected hosted validation, attempt 2 successfully imported the approved private checkpoint proof, validated the exact candidate, published its safe summary, and removed private runner files. No required validator was skipped.

Codex reported no major issues on 1f0a2cf224; all three addressed onboarding review threads are resolved. The independent fresh-reader check passed all five requested questions on this head, using repository files only; no material instruction gaps were found. No tests were run as part of that reader check.

The human-approved handoff used only the checked metadata scope, with no prompts or transcripts. Both temporary environment secrets, the owned branch policy, and local transport copies were removed. The prior environment protection was restored and verified by read-back. Customer-owned native checkpoints and backups remain private and intact.

All required premerge CI and review gates passed. With explicit human approval, this PR was squash-merged as 580956db5e3441128df23c08e9a54ea8393f71fc. Main's Quality workflow passed on that commit. Its product-validation workflow, attempt 2, also passed after the separately approved metadata-only push-proof handoff. Source revision resolution, approved proof import, exact-candidate validation, safe summary publication, and private runner cleanup all completed successfully. Both temporary proof inputs and the owned main branch policy were removed; prior environment settings were restored and verified by read-back. All four required checks passed on the merged commit. No tag, package publication, or deployment was performed.

Repository settings and lesson record

GitHub private vulnerability reporting was enabled and verified by API read-back. Description, documentation homepage, and topics were applied and read back; obsolete Graphite and unsupported Scorecard topics were removed. Temporary proof protection and secrets were restored or removed after successful validation; the existing environment was preserved.

Lesson-to-change record maps all 14 lessons to the implemented workflow.

Merge was separately approved by the human user and completed. Tagging, package publication, and deployment remain outside this authorization.

[hudsonaikins]

@codex review

Review candidate 5a8ebfece7cfcb2c6b65aefa6ac774f369081aed against main. Check the documentation and repository harness changes, including docs-check coverage and any actionable release blockers.

Please also act as a fresh reader and answer: What is Tabellio? How is the repository organized? How do I run the documented first-use demo? How do I check a contribution? Where does unfinished work resume?

Local exact-head product validation passed. Hosted Tests, Fallow changed-code, and Package dry-run passed on this candidate. Hosted product validation remains blocked on the separately approved private checkpoint handoff. No merge, tag, package publication, or deployment is authorized.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a8ebfece7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[hudsonaikins]

@codex review

Review current head dcb8f01fdc88243ff7655e43b53489dcadad2042. All three initial findings are fixed: README and first-use requirements include createdb; contribution guidance documents the scanner's Apple silicon macOS/x86-64 Linux support and a Linux development fallback; installed documentation uses the packaged PR template.

Required local checks and committed exact-head product validation passed (216.50 seconds, provider cost $0, complete cost telemetry). Hosted validation still needs a checked, separately approved private proof handoff; the current two-part transport cannot carry the exported bundle. No limits were raised or proof inputs uploaded.

Please confirm the fixes and complete the fresh-reader check: what is Tabellio, how is this repository organized, how do I run the demo, how do I check a contribution, and where does unfinished work resume? No merge or release action is authorized.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: dcb8f01fdc

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[hudsonaikins]

@codex review

Review current head 1f0a2cf224b50c7575121af2144a98cbbbe93049. The new change fixes the private checkpoint export size blocker while preserving all original native commit/tree/blob identities, selected metadata, privacy checks, and two-part limits. Unit tests cover full commit ancestry, clean import, and exclusion of transcripts and unselected metadata. Local exact-head validation passed. A clean consumer also passed the existing loader, pinned Entire 0.7.7 capture, and owned cleanup using locally simulated runner variables. Hosted validation still awaits separately approved scope sharing and protection. Do not merge or release.

[hudsonaikins]

@codex Please perform a read-only fresh-reader check of commit 1f0a2cf224b50c7575121af2144a98cbbbe93049, using the repository files as your source. Answer briefly with file references: (1) What is Tabellio? (2) How is the repository organized? (3) How do I run the published first-use demo, including its prerequisites? (4) How do I check a contribution? (5) Where does unfinished work resume, and which records determine readiness? Identify any blocker that prevents a new reader from answering. Do not change files, create a PR, merge, publish, tag, or deploy.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 1f0a2cf224

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".