docs: split quickstart into Code, UI, and CLI guides#96
Open
s-adamantine wants to merge 8 commits intomainfrom
Open
docs: split quickstart into Code, UI, and CLI guides#96s-adamantine wants to merge 8 commits intomainfrom
s-adamantine wants to merge 8 commits intomainfrom
Conversation
…sing Code' and 'Using the Scaffold App'
…wo common approaches
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThe PR restructures the Getting Started section by converting the Quickstart page from a detailed tutorial into a navigation hub with three separate guides. The navigation hierarchy is updated, and the guide content is split into code-based, UI-based, and CLI-based approaches across new documentation files. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.beads/issues.jsonl:
- Line 121: The PR includes unrelated edits to the tracker file
.beads/issues.jsonl (notably the JSON entry with "id":"docs-yzy.4") which should
be removed from this feature PR; revert or remove any changes to
.beads/issues.jsonl (undo the commit or git restore --staged/checkout the file),
then amend the branch so only the intended documentation files remain in the
diff (documentation/pages/... files mentioned in the task). Ensure the tracker
file is unchanged in this PR and push an amended commit (or create a separate
PR) if Beads state must be updated separately.
In `@lib/navigation.js`:
- Around line 18-20: The navigation contains duplicate entries for the CLI page
(path "/tools/hypercerts-cli") which causes flattenNavigation() to push the page
twice and break getPrevNext() and search; fix by deduplicating entries in
flattenNavigation(): track seen paths (e.g., a Set) and skip pushing any item
whose path was already added (or normalize/resolve the path before checking), so
the duplicate "/tools/hypercerts-cli" is ignored and getPrevNext() will operate
on a single unique list.
In `@pages/getting-started/creating-your-first-hypercert.md`:
- Line 229: The documentation currently omits `subject` from the required-fields
sentence; update the sentence that lists required fields so it includes
`subject` (i.e., "Required fields are `evaluators`, `summary`, `createdAt`, and
`subject`") to match the example and earlier statement that evaluations must be
attached to a record; ensure the note about `subject` being a single strong
reference remains unchanged.
- Line 70: Update the broken CEL link in the markdown line containing "**Work
scopes**" that currently points to "/core-concepts/work-scopes" so it points to
the correct path "/core-concepts/cel-work-scopes"; locate the line with the text
"[CEL expression](/core-concepts/work-scopes)" and change the URL to "[CEL
expression](/core-concepts/cel-work-scopes)" so the link resolves correctly.
In `@pages/getting-started/quickstart.md`:
- Around line 2-3: The meta description frontmatter ("description") currently
reads "Create your first hypercert — via code or the UI" but the page now routes
to three guides (code, UI, CLI); update the description frontmatter to include
the CLI and accurately reflect all options (e.g., "Create your first hypercert —
via code, the CLI, or the UI") by editing the description value in the page
frontmatter (see the description field and title metadata).
In `@pages/getting-started/using-the-scaffold-app.md`:
- Line 10: Update the section headings that currently use "### Step …" to
second-level headings "## Step …" so the document's heading hierarchy is
preserved; locate each occurrence of the strings like "### Step 1 — Sign in"
(and the other "### Step …" instances at the commented locations) and replace
the leading "###" with "##" to promote them to H2.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a10debb7-7207-4d60-b5bf-e519e0dc4a9d
📒 Files selected for processing (5)
.beads/issues.jsonllib/navigation.jspages/getting-started/creating-your-first-hypercert.mdpages/getting-started/quickstart.mdpages/getting-started/using-the-scaffold-app.md
| {"id":"docs-yzy.2","title":"Update navigation and rewrite blockchain-integration.md to redirect to planned page","description":"## Files\n- documentation/lib/navigation.js (modify)\n- documentation/pages/getting-started/infrastructure/blockchain-integration.md (modify)\n- documentation/pages/getting-started/infrastructure/portability-and-scaling.md (modify)\n- documentation/pages/getting-started/the-hypercerts-infrastructure.md (modify — just the link on line 78)\n\n## What to do\n\n### 1. Update navigation.js\n\nChange line 25 from:\n```js\n{ title: 'Blockchain Integration', path: '/getting-started/infrastructure/blockchain-integration' },\n```\nto:\n```js\n{ title: 'Funding \u0026 Tokenization (Planned)', path: '/architecture/planned-funding-and-tokenization' },\n```\n\nAlso add the new page to the Understand section, after \"Data Flow \u0026 Lifecycle\" (line 30). Add:\n```js\n{ title: 'Planned: Funding \u0026 Tokenization', path: '/architecture/planned-funding-and-tokenization' },\n```\n\nWait — actually, since it's already linked as a child of \"The Hypercerts Infrastructure\", just update that child entry. Don't add a duplicate. So the only change is line 25.\n\n### 2. Rewrite blockchain-integration.md\n\nThis file currently has the old mint-on-create / lazy minting / batch anchoring / hybrid ownership patterns. Replace the entire content with a redirect notice:\n\n```markdown\n---\ntitle: Funding \u0026 Tokenization\n---\n\n# Funding \u0026 Tokenization\n\nThis content has moved to [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\n```\n\n### 3. Update portability-and-scaling.md\n\nLines 36-38 have \"Blockchain scalability\" section that says \"On-chain operations (minting, transfers, sales) are expensive...\" — this is planned content. Replace with:\n\n```markdown\n#### On-chain scalability (planned)\n\nThe on-chain funding and tokenization layer is not yet implemented. When built, on-chain operations will be expensive, so hypercerts will minimize on-chain activity by keeping rich data on ATProto. Only frozen snapshots and funding flows will touch the blockchain. For details on the planned on-chain design, see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\n```\n\nAlso lines 50-52 have \"Access control via smart contracts\" with token-gated data. Replace with:\n\n```markdown\n#### Access control via smart contracts (planned)\n\nIn the planned design, on-chain tokens could have access control logic — for example, granting read access to private ATProto records only to token holders. This is a potential future feature. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for details.\n```\n\n### 4. Update the-hypercerts-infrastructure.md line 78\n\nChange:\n```\n- [Blockchain Integration](/getting-started/infrastructure/blockchain-integration) — minting patterns and on-chain ownership\n```\nto:\n```\n- [Funding \u0026 Tokenization (Planned)](/architecture/planned-funding-and-tokenization) — freeze-then-fund model and on-chain ownership design\n```\n\n## Test\ngrep -q 'planned-funding-and-tokenization' documentation/lib/navigation.js \u0026\u0026 \\\ngrep -q 'moved to' documentation/pages/getting-started/infrastructure/blockchain-integration.md \u0026\u0026 \\\ngrep -q 'planned-funding-and-tokenization' documentation/pages/getting-started/the-hypercerts-infrastructure.md \u0026\u0026 \\\ngrep -q 'not yet implemented' documentation/pages/getting-started/infrastructure/portability-and-scaling.md \u0026\u0026 \\\n! grep -q 'mints an NFT\\|Mint-on-create\\|Lazy minting' documentation/pages/getting-started/infrastructure/blockchain-integration.md \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Add duplicate nav entries\n- Delete blockchain-integration.md (keep it as a redirect so old links work)\n- Change anything else in navigation.js\n- Change anything else in the-hypercerts-infrastructure.md besides line 78\n- Change anything else in portability-and-scaling.md besides the blockchain scalability and token-gated sections","status":"closed","priority":1,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T17:12:50.318417+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T17:18:08.762614+13:00","closed_at":"2026-02-16T17:18:08.762614+13:00","close_reason":"e8dd74d Update navigation and redirect blockchain-integration to planned funding page","labels":["scope:small"],"dependencies":[{"issue_id":"docs-yzy.2","depends_on_id":"docs-yzy","type":"parent-child","created_at":"2026-02-16T17:12:50.31972+13:00","created_by":"sharfy-test.climateai.org"},{"issue_id":"docs-yzy.2","depends_on_id":"docs-yzy.1","type":"blocks","created_at":"2026-02-16T17:14:24.044876+13:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"docs-yzy.3","title":"Strip planned content from architecture/overview.md and architecture/data-flow-and-lifecycle.md — link to planned page","description":"## Files\n- documentation/pages/architecture/overview.md (modify)\n- documentation/pages/architecture/data-flow-and-lifecycle.md (modify)\n\n## What to do\n\nRemove detailed planned/TBD content from these two architecture pages. Replace with brief mentions and links to /architecture/planned-funding-and-tokenization. The main docs should describe what EXISTS TODAY (ATProto data layer) and only briefly note that on-chain funding is planned.\n\n### architecture/overview.md\n\n**Line 8:** Change to: \"The Hypercerts Protocol uses AT Protocol for data portability. On-chain anchoring for ownership and funding is [planned](/architecture/planned-funding-and-tokenization).\"\n\n**Line 18 (Ownership Layer):** Condense to 1-2 sentences max: \"The **Ownership Layer** is planned but not yet implemented. The intended design uses a freeze-then-fund model where hypercerts are frozen and anchored on-chain before funding — ensuring funders know exactly what they are paying for. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for details.\"\n\n**Lines 48-70 (Ownership Layer Deep Dive):** DELETE this entire section (Anchoring, Tokenization, Funding Mechanisms, Multi-Chain Support). Replace with a single short paragraph:\n\n\"## Ownership Layer (Planned)\n\nThe ownership layer is not yet implemented. The planned design freezes ATProto records and anchors them on-chain before funding, ensuring funders know exactly what they are paying for. For the full planned design — including anchoring, tokenization, funding mechanisms, and multi-chain support — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\"\n\n**Lines 72-95 (How the Layers Connect):** Keep the first paragraph about content living on ATProto (line 76). Remove lines 78-80 (detailed planned flow) and the cross-layer example (lines 86-95). Replace with:\n\n\"A hypercert's **ownership and funding state** will live on-chain once the tokenization layer is built. The planned bridge is a freeze-then-fund mechanism. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for the full cross-layer design.\"\n\nKeep the callout (lines 82-84) but simplify: \"The separation matters. ATProto provides data portability — users can switch servers, applications can read across the network, and records outlive any single platform. On-chain anchoring will provide ownership and funding guarantees. Neither layer can provide both properties alone.\"\n\n**Lines 105-107 (Why Not Fully Off-Chain?):** Condense. Keep the core point (mutable records are fine for collaboration but funding requires immutability) but remove the detailed freeze-then-fund explanation. Add link.\n\n**Lines 115-119 (Why This Separation):** Simplify. Remove \"through the planned freeze-then-fund mechanism\" and \"Once the tokenization layer is built\". Just say: \"Each layer does what it does best. ATProto handles identity, data portability, and schemas. On-chain anchoring will handle ownership, funding, and immutability. This separation reduces costs, increases flexibility, and maintains portability.\"\n\n**Lines 121-131 (What This Enables):** Remove \"(Planned)\" labels and the detailed planned descriptions. Keep the 4 bullet points but make them concise. For the two that work today, keep as-is. For the two that are planned, just say \"planned\" in one phrase and link to the planned page.\n\n**Add to Next Steps:** Add a link: \"For the planned on-chain funding and tokenization design, see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\"\n\n### architecture/data-flow-and-lifecycle.md\n\n**Line 22 (Funding summary):** Condense to: \"**Funding** connects ownership to the claim. The on-chain funding layer is [planned but not yet implemented](/architecture/planned-funding-and-tokenization). The intended design freezes ATProto records before funding to ensure funders know exactly what they are paying for.\"\n\n**Line 24 (Accumulation):** Simplify to: \"**Accumulation** continues indefinitely. More evaluations arrive. Additional evidence gets attached. The data layer continues evolving.\"\n\n**Line 29 (diagram):** Change \"On-chain (planned)\" to just \"On-chain*\" and add a footnote: \"*On-chain layer is planned. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\"\n\n**Lines 146-187 (Stage 5: Funding \u0026 Ownership):** DELETE the detailed content. Replace with a short section:\n\n\"## Stage 5: Funding \u0026 Ownership (Planned)\n\nThe on-chain funding layer is not yet implemented. The planned design: before a hypercert can be funded, its ATProto records are frozen and the snapshot is anchored on-chain. This ensures funders know exactly what they are paying for — the cert's contents cannot change after freezing.\n\nFor the full planned design — including anchoring, tokenization, funding mechanisms, funding readiness patterns, and multi-chain support — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\"\n\n**Lines 205-218 (Ownership Transfers, Long-Term Value in Stage 6):** Remove the \"Ownership Transfers\" subsection entirely (it's all planned content). Keep \"Long-Term Value\" but simplify: \"The separation of data and ownership enables long-term value accumulation. A hypercert's reputation can grow as evaluations accumulate. The data remains portable and accessible regardless of future ownership changes.\"\n\nRemove the timeline diagram (lines 213-218) or simplify it to only show what exists today:\n```\nTime →\n─────────────────────────────────────────────────────────\nCreation Evaluation 1 Discovery Evaluation 2 Evidence Evaluation 3\n ↓ ↓ ↓ ↓ ↓ ↓\n PDS PDS-Eva1 Indexer PDS-Eva2 PDS PDS-Eva3\n```\n\n## Test\n! grep -q 'Multi-Chain Support' documentation/pages/architecture/overview.md \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/architecture/overview.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/architecture/data-flow-and-lifecycle.md | grep -qv '^0$' \u0026\u0026 \\\n! grep -q 'Anchoring (Planned)' documentation/pages/architecture/overview.md \u0026\u0026 \\\n! grep -q 'Tokenization (Planned)' documentation/pages/architecture/overview.md \u0026\u0026 \\\n! grep -q 'Funding Mechanisms (Planned)' documentation/pages/architecture/overview.md \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Remove the Data Layer sections — those describe what exists today\n- Remove the Key Design Decisions section entirely — just simplify it\n- Remove the \"What This Enables\" section — just simplify it\n- Add new planned content — we're REMOVING it and linking to the dedicated page\n- Change Stages 1-4 in data-flow-and-lifecycle.md\n- Change the Cross-PDS References or \"What This Flow Enables\" sections in data-flow-and-lifecycle.md","status":"closed","priority":1,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T17:13:45.724521+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T17:19:22.582072+13:00","closed_at":"2026-02-16T17:19:22.582072+13:00","close_reason":"4ed89bd Strip planned content from architecture docs and link to planned page","labels":["scope:medium"],"dependencies":[{"issue_id":"docs-yzy.3","depends_on_id":"docs-yzy","type":"parent-child","created_at":"2026-02-16T17:13:45.725402+13:00","created_by":"sharfy-test.climateai.org"},{"issue_id":"docs-yzy.3","depends_on_id":"docs-yzy.1","type":"blocks","created_at":"2026-02-16T17:14:24.15891+13:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"docs-yzy.4","title":"Strip planned content from 5 getting-started and reference pages — link to planned page","description":"## Files\n- documentation/pages/getting-started/the-hypercerts-infrastructure.md (modify)\n- documentation/pages/getting-started/why-atproto.md (modify)\n- documentation/pages/getting-started/why-were-building-hypercerts.md (modify)\n- documentation/pages/getting-started/introduction-to-impact-claims.md (modify)\n- documentation/pages/reference/faq.md (modify)\n\n## What to do\n\nRemove detailed planned/TBD content from these 5 pages. Replace with brief mentions and links to /architecture/planned-funding-and-tokenization.\n\n### the-hypercerts-infrastructure.md\n\n**Line 7:** Change to: \"Hypercerts runs on AT Protocol for data. On-chain anchoring for ownership and funding is [planned](/architecture/planned-funding-and-tokenization).\"\n\n**Lines 19-23 (The funding layer section):** Condense to 2-3 sentences max:\n\n\"#### The funding layer: on-chain anchoring (planned)\n\nThe on-chain funding layer is not yet implemented. The planned design uses a freeze-then-fund model: before a hypercert can be funded, its ATProto records are frozen and anchored on-chain, ensuring funders know exactly what they are paying for. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for the full design.\"\n\n**Lines 25-29 (How the layers connect):** Condense. Keep the AT-URI example. Remove the detailed planned flow. Just say: \"A claim can exist on ATProto without ever being frozen for funding. The two layers are loosely coupled and complement each other.\"\n\n**Lines 53-57 (Step 4):** Condense to:\n\n\"#### 4. The hypercert is frozen and funded (planned)\n\nIn the planned design, Carol's funding app will freeze Alice's hypercert and anchor the snapshot on-chain. Carol knows exactly what she is paying for because the frozen claim cannot change. The tokenization layer is not yet implemented — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for details.\"\n\n### why-atproto.md\n\n**Lines 49-51 (ATProto + Blockchain section):** Condense to:\n\n\"ATProto handles the data layer — claims, evidence, evaluations, trust signals. On-chain anchoring is planned to handle the funding layer. The intended design: hypercerts are frozen and anchored on-chain before funding, ensuring funders know exactly what they're paying for. The tokenization layer is not yet implemented — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for the full design.\"\n\n### why-were-building-hypercerts.md\n\n**Line 182:** Keep as-is: \"That's where onchain anchoring comes in — and eventually, tokenization.\"\n\n**Lines 184-192 (The Ownership \u0026 Funding Layer):** Condense to:\n\n\"#### The Funding Layer: On-chain Anchoring (Planned)\n\nATProto provides the data layer. But funding requires a stronger guarantee: funders need to know that what they're paying for won't change after the fact. The planned approach is freeze-then-fund — before a hypercert can be funded, its ATProto records are frozen and anchored on-chain. The tokenization layer is not yet implemented. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for the full design.\"\n\n### introduction-to-impact-claims.md\n\n**Line 21:** Condense to: \"Hypercerts can exist as a standalone activity claim, or they can be [frozen and funded](/architecture/planned-funding-and-tokenization) on-chain (planned).\"\n\n### faq.md\n\n**Line 18 (How is this different):** Condense to: \"The new protocol is built on AT Protocol instead of purely on-chain. This gives data portability, richer schemas, and lower costs. On-chain anchoring for funding is [planned](/architecture/planned-funding-and-tokenization) but not yet implemented.\"\n\n**Lines 20-22 (Do I need a blockchain wallet?):** Condense to: \"Not to create or evaluate hypercerts — you only need an ATProto account (DID). A blockchain wallet will be needed for on-chain funding once the [tokenization layer](/architecture/planned-funding-and-tokenization) is built.\"\n\n**Lines 37-38 (How do I fund?):** Condense to: \"The on-chain funding layer is not yet implemented. The planned design freezes ATProto records before funding to ensure funders know exactly what they are paying for. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for details.\"\n\n**Lines 44-46 (What chains?):** Condense to: \"The protocol intends to be chain-agnostic. The on-chain layer is not yet implemented — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\"\n\n## Test\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/the-hypercerts-infrastructure.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/why-atproto.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/why-were-building-hypercerts.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/introduction-to-impact-claims.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/reference/faq.md | grep -qv '^0$' \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Remove the data layer sections — those describe what exists today\n- Remove the data flow walkthrough (Steps 1-3 in infrastructure) — those are accurate\n- Remove the Data Integrity and Trust section in infrastructure — accurate\n- Change anything in why-were-building-hypercerts.md before line 172\n- Add new planned content — we're condensing and linking\n- Change the \"Keep Reading\" links in infrastructure (except the blockchain-integration link which is handled by another task)","status":"closed","priority":2,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T17:14:18.331984+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-03-03T14:42:32.355416674+06:00","closed_at":"2026-02-17T05:24:43.922182+13:00","labels":["scope:medium"],"dependencies":[{"issue_id":"docs-yzy.4","depends_on_id":"docs-yzy","type":"parent-child","created_at":"2026-02-16T17:14:18.333338+13:00","created_by":"sharfy-test.climateai.org"},{"issue_id":"docs-yzy.4","depends_on_id":"docs-yzy.1","type":"blocks","created_at":"2026-02-16T17:14:24.250458+13:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"docs-yzy.4","title":"Strip planned content from 5 getting-started and reference pages — link to planned page","description":"## Files\n- documentation/pages/getting-started/the-hypercerts-infrastructure.md (modify)\n- documentation/pages/getting-started/why-atproto.md (modify)\n- documentation/pages/getting-started/why-were-building-hypercerts.md (modify)\n- documentation/pages/getting-started/introduction-to-impact-claims.md (modify)\n- documentation/pages/reference/faq.md (modify)\n\n## What to do\n\nRemove detailed planned/TBD content from these 5 pages. Replace with brief mentions and links to /architecture/planned-funding-and-tokenization.\n\n### the-hypercerts-infrastructure.md\n\n**Line 7:** Change to: \"Hypercerts runs on AT Protocol for data. On-chain anchoring for ownership and funding is [planned](/architecture/planned-funding-and-tokenization).\"\n\n**Lines 19-23 (The funding layer section):** Condense to 2-3 sentences max:\n\n\"#### The funding layer: on-chain anchoring (planned)\n\nThe on-chain funding layer is not yet implemented. The planned design uses a freeze-then-fund model: before a hypercert can be funded, its ATProto records are frozen and anchored on-chain, ensuring funders know exactly what they are paying for. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for the full design.\"\n\n**Lines 25-29 (How the layers connect):** Condense. Keep the AT-URI example. Remove the detailed planned flow. Just say: \"A claim can exist on ATProto without ever being frozen for funding. The two layers are loosely coupled and complement each other.\"\n\n**Lines 53-57 (Step 4):** Condense to:\n\n\"#### 4. The hypercert is frozen and funded (planned)\n\nIn the planned design, Carol's funding app will freeze Alice's hypercert and anchor the snapshot on-chain. Carol knows exactly what she is paying for because the frozen claim cannot change. The tokenization layer is not yet implemented — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for details.\"\n\n### why-atproto.md\n\n**Lines 49-51 (ATProto + Blockchain section):** Condense to:\n\n\"ATProto handles the data layer — claims, evidence, evaluations, trust signals. On-chain anchoring is planned to handle the funding layer. The intended design: hypercerts are frozen and anchored on-chain before funding, ensuring funders know exactly what they're paying for. The tokenization layer is not yet implemented — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for the full design.\"\n\n### why-were-building-hypercerts.md\n\n**Line 182:** Keep as-is: \"That's where onchain anchoring comes in — and eventually, tokenization.\"\n\n**Lines 184-192 (The Ownership \u0026 Funding Layer):** Condense to:\n\n\"#### The Funding Layer: On-chain Anchoring (Planned)\n\nATProto provides the data layer. But funding requires a stronger guarantee: funders need to know that what they're paying for won't change after the fact. The planned approach is freeze-then-fund — before a hypercert can be funded, its ATProto records are frozen and anchored on-chain. The tokenization layer is not yet implemented. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for the full design.\"\n\n### introduction-to-impact-claims.md\n\n**Line 21:** Condense to: \"Hypercerts can exist as a standalone activity claim, or they can be [frozen and funded](/architecture/planned-funding-and-tokenization) on-chain (planned).\"\n\n### faq.md\n\n**Line 18 (How is this different):** Condense to: \"The new protocol is built on AT Protocol instead of purely on-chain. This gives data portability, richer schemas, and lower costs. On-chain anchoring for funding is [planned](/architecture/planned-funding-and-tokenization) but not yet implemented.\"\n\n**Lines 20-22 (Do I need a blockchain wallet?):** Condense to: \"Not to create or evaluate hypercerts — you only need an ATProto account (DID). A blockchain wallet will be needed for on-chain funding once the [tokenization layer](/architecture/planned-funding-and-tokenization) is built.\"\n\n**Lines 37-38 (How do I fund?):** Condense to: \"The on-chain funding layer is not yet implemented. The planned design freezes ATProto records before funding to ensure funders know exactly what they are paying for. See [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization) for details.\"\n\n**Lines 44-46 (What chains?):** Condense to: \"The protocol intends to be chain-agnostic. The on-chain layer is not yet implemented — see [Planned: Funding \u0026 Tokenization](/architecture/planned-funding-and-tokenization).\"\n\n## Test\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/the-hypercerts-infrastructure.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/why-atproto.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/why-were-building-hypercerts.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/getting-started/introduction-to-impact-claims.md | grep -qv '^0$' \u0026\u0026 \\\ngrep -c 'planned-funding-and-tokenization' documentation/pages/reference/faq.md | grep -qv '^0$' \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Remove the data layer sections — those describe what exists today\n- Remove the data flow walkthrough (Steps 1-3 in infrastructure) — those are accurate\n- Remove the Data Integrity and Trust section in infrastructure — accurate\n- Change anything in why-were-building-hypercerts.md before line 172\n- Add new planned content — we're condensing and linking\n- Change the \"Keep Reading\" links in infrastructure (except the blockchain-integration link which is handled by another task)","status":"closed","priority":2,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T17:14:18.331984+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-17T05:24:43.922182+13:00","closed_at":"2026-02-17T05:24:43.922182+13:00","close_reason":"Superseded by PR #4 merge — all planned-funding-and-tokenization references updated to funding-and-tokenization","labels":["scope:medium"],"dependencies":[{"issue_id":"docs-yzy.4","depends_on_id":"docs-yzy","type":"parent-child","created_at":"2026-02-16T17:14:18.333338+13:00","created_by":"sharfy-test.climateai.org"},{"issue_id":"docs-yzy.4","depends_on_id":"docs-yzy.1","type":"blocks","created_at":"2026-02-16T17:14:24.250458+13:00","created_by":"sharfy-test.climateai.org"}]} |
There was a problem hiding this comment.
Remove unrelated Beads tracker updates from this PR.
These .beads/issues.jsonl edits don't appear to implement the quickstart split itself, so they add review noise and create avoidable merge-conflict churn in a shared tracker file. Please keep the feature PR scoped to the documentation pages/navigation changes and drop these tracker-state updates unless updating Beads is explicitly part of the feature.
Also applies to: 132-133
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.beads/issues.jsonl at line 121, The PR includes unrelated edits to the
tracker file .beads/issues.jsonl (notably the JSON entry with "id":"docs-yzy.4")
which should be removed from this feature PR; revert or remove any changes to
.beads/issues.jsonl (undo the commit or git restore --staged/checkout the file),
then amend the branch so only the intended documentation files remain in the
diff (documentation/pages/... files mentioned in the task). Ensure the tracker
file is unchanged in this PR and push an amended commit (or create a separate
PR) if Beads state must be updated separately.
Comment on lines
+18
to
+20
| { | ||
| title: "Using the CLI", | ||
| path: "/tools/hypercerts-cli", |
There was a problem hiding this comment.
Avoid adding the CLI page twice to the nav tree.
/tools/hypercerts-cli already exists under Tools on Lines 71-72. flattenNavigation() pushes both entries, so getPrevNext() will resolve the CLI page against the first match and the page can end up with the wrong neighbors; search will also surface duplicates.
One way to keep the cross-link while fixing prev/next/search
-export function flattenNavigation(nav = navigation, currentSection = "") {
+export function flattenNavigation(
+ nav = navigation,
+ currentSection = "",
+ seen = new Set(),
+) {
const result = [];
for (const item of nav) {
const section = item.section || currentSection;
- if (item.path) {
+ if (item.path && !seen.has(item.path)) {
+ seen.add(item.path);
result.push({ title: item.title, path: item.path, section });
}
if (item.children) {
- result.push(...flattenNavigation(item.children, section));
+ result.push(...flattenNavigation(item.children, section, seen));
}
}
return result;
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@lib/navigation.js` around lines 18 - 20, The navigation contains duplicate
entries for the CLI page (path "/tools/hypercerts-cli") which causes
flattenNavigation() to push the page twice and break getPrevNext() and search;
fix by deduplicating entries in flattenNavigation(): track seen paths (e.g., a
Set) and skip pushing any item whose path was already added (or
normalize/resolve the path before checking), so the duplicate
"/tools/hypercerts-cli" is ignored and getPrevNext() will operate on a single
unique list.
| The activity claim is the core record — it describes what work was done, when, and in what scope. Here's how each field maps to the [activity lexicon](/lexicons/hypercerts-lexicons/activity-claim): | ||
|
|
||
| - **Contributors** are embedded directly in the activity claim as a `contributors` array. Each entry has a `contributorIdentity` (inline DID string, or a strong reference to a [`contributorInformation`](/lexicons/hypercerts-lexicons/contribution) record), an optional `contributionWeight`, and an optional `contributionDetails` (inline role string, or a strong reference to an [`org.hypercerts.claim.contribution`](/lexicons/hypercerts-lexicons/contribution) record for richer detail). | ||
| - **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network. |
There was a problem hiding this comment.
Fix the CEL Work Scopes link.
Line 70 points to /core-concepts/work-scopes, but the actual page path in lib/navigation.js is /core-concepts/cel-work-scopes. The current link will 404.
Suggested fix
-- **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network.
+- **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/cel-work-scopes) for machine-evaluable queries across the network.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network. | |
| - **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/cel-work-scopes) for machine-evaluable queries across the network. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/getting-started/creating-your-first-hypercert.md` at line 70, Update
the broken CEL link in the markdown line containing "**Work scopes**" that
currently points to "/core-concepts/work-scopes" so it points to the correct
path "/core-concepts/cel-work-scopes"; locate the line with the text "[CEL
expression](/core-concepts/work-scopes)" and change the URL to "[CEL
expression](/core-concepts/cel-work-scopes)" so the link resolves correctly.
| }); | ||
| ``` | ||
|
|
||
| Required fields are `evaluators`, `summary`, and `createdAt`. Unlike attachments and measurements, `subject` is a single strong reference (not an array). The optional `score` object takes integer `min`, `max`, and `value` fields. |
There was a problem hiding this comment.
Include subject in the required-fields list.
Line 229 currently reads as if an evaluation can be created without being attached to a record. That contradicts the section above and the example on Lines 213-215.
Suggested fix
-Required fields are `evaluators`, `summary`, and `createdAt`. Unlike attachments and measurements, `subject` is a single strong reference (not an array). The optional `score` object takes integer `min`, `max`, and `value` fields.
+Required fields are `subject`, `evaluators`, `summary`, and `createdAt`. Unlike attachments and measurements, `subject` is a single strong reference (not an array). The optional `score` object takes integer `min`, `max`, and `value` fields.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Required fields are `evaluators`, `summary`, and `createdAt`. Unlike attachments and measurements, `subject` is a single strong reference (not an array). The optional `score` object takes integer `min`, `max`, and `value` fields. | |
| Required fields are `subject`, `evaluators`, `summary`, and `createdAt`. Unlike attachments and measurements, `subject` is a single strong reference (not an array). The optional `score` object takes integer `min`, `max`, and `value` fields. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/getting-started/creating-your-first-hypercert.md` at line 229, The
documentation currently omits `subject` from the required-fields sentence;
update the sentence that lists required fields so it includes `subject` (i.e.,
"Required fields are `evaluators`, `summary`, `createdAt`, and `subject`") to
match the example and earlier statement that evaluations must be attached to a
record; ensure the note about `subject` being a single strong reference remains
unchanged.
Comment on lines
+2
to
+3
| title: Creating Your First Hypercert | ||
| description: Create your first hypercert — via code or the UI. |
There was a problem hiding this comment.
Mention the CLI in the page description.
Line 3 still says “via code or the UI”, but this page now routes to three guides. The meta description should match the actual options.
Suggested fix
-description: Create your first hypercert — via code or the UI.
+description: Create your first hypercert — via code, the UI, or the CLI.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| title: Creating Your First Hypercert | |
| description: Create your first hypercert — via code or the UI. | |
| title: Creating Your First Hypercert | |
| description: Create your first hypercert — via code, the UI, or the CLI. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/getting-started/quickstart.md` around lines 2 - 3, The meta description
frontmatter ("description") currently reads "Create your first hypercert — via
code or the UI" but the page now routes to three guides (code, UI, CLI); update
the description frontmatter to include the CLI and accurately reflect all
options (e.g., "Create your first hypercert — via code, the CLI, or the UI") by
editing the description value in the page frontmatter (see the description field
and title metadata).
|
|
||
| The [Scaffold app](https://hypercerts-scaffold.vercel.app) lets you create a full hypercert through a guided wizard — no code required. For the code-based approach, see [Using Code](/getting-started/creating-your-first-hypercert). | ||
|
|
||
| ### Step 1 — Sign in |
There was a problem hiding this comment.
Use ## for the step sections.
The page jumps from the H1 on Line 6 straight to H3s, so it trips MD001 and leaves the heading hierarchy broken. Promote each ### Step … heading to ##.
Suggested fix
-### Step 1 — Sign in
+## Step 1 — Sign in
@@
-### Step 2 — Basic info
+## Step 2 — Basic info
@@
-### Step 3 — Add attachments
+## Step 3 — Add attachments
@@
-### Step 4 — Add location *(optional)*
+## Step 4 — Add location *(optional)*
@@
-### Step 5 — Add measurements *(optional)*
+## Step 5 — Add measurements *(optional)*
@@
-### Step 6 — Add evaluations *(optional)*
+## Step 6 — Add evaluations *(optional)*
@@
-### Step 7 — Done
+## Step 7 — DoneAlso applies to: 17-17, 36-36, 51-51, 65-65, 81-81, 96-96
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 10-10: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/getting-started/using-the-scaffold-app.md` at line 10, Update the
section headings that currently use "### Step …" to second-level headings "##
Step …" so the document's heading hierarchy is preserved; locate each occurrence
of the strings like "### Step 1 — Sign in" (and the other "### Step …" instances
at the commented locations) and replace the leading "###" with "##" to promote
them to H2.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Split the 330-line quickstart page into a grouped section with three approaches:
createRecordexampleshcCLI tool pageThe parent "Creating Your First Hypercert" page is now a short intro linking to all three. Setup and auth moved into "Using Code" since it's only needed there.
Fixes https://linear.app/hypercerts/issue/HYPER-142/quickstart-page
Summary by CodeRabbit
Release Notes
Documentation
New Features