Docs: SDK alignment, architecture updates, new pages, and quality fixes#31
Merged
Conversation
- Align all Get Started pages with develop branch SDK and Lexicon APIs (rights fields, method names, return types, auth config, contributions format) - Update all 5 Architecture pages with cross-references, expanded content, and corrections from develop branch - Redesign architecture-stack.svg with detailed three-layer diagram - Add Hypercerts SDK reference page (tools/sdk.md) - Add new lexicon pages: funding-receipt, acknowledgement, badge-award, badge-definition, badge-response, profile - Rename General Lexicons to Certified Lexicons - Rename why-atproto.md to why-at-protocol.md - Fix CodeRabbit review issues (terminology, verb agreement, capitalization) - Update navigation and index page to match all changes
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR restructures site navigation and terminology (ATProto → AT Protocol), adds Hypercerts SDK docs, introduces Certified Lexicons and several lexicon pages (badges, profile, funding receipts, acknowledgement), updates many getting-started examples and SDK/repo API shapes, and reorganizes architecture/indexer and tooling docs; plus UI/layout and draft-page workflow changes. Changes
Sequence Diagram(s)sequenceDiagram
participant Client as Client (App)
participant SDK as Hypercerts SDK
participant PDS as User PDS (AT Protocol)
participant Indexer as Hyperindex / Indexer
Client->>SDK: initiate OAuth / authenticate
SDK->>PDS: redirect request / ask user to authorize
PDS-->>SDK: auth token via callback
SDK->>PDS: create records (hypercert, rights, attachments)
PDS-->>SDK: return AT-URIs + CIDs
SDK->>Indexer: emit/index events (Jetstream/Hyperindex)
Indexer-->>SDK: indexed data / GraphQL results
SDK-->>Client: return result.hypercertUri / result.hypercertCid
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 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 |
- Rewrite based on actual hyperboards.org product features: treemap layouts, drag-to-resize editing, iframe embedding, ATProto sign-in, dashboard - Add embedding code example, tech stack table - Update navigation and index page references - Rename hyperboard.md → hyperboards.md to match product name
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
pages/getting-started/working-with-evaluations.md (1)
13-34:⚠️ Potential issue | 🟡 MinorInconsistent auth pattern: OAuth config paired with
sdk.restoreSession().The SDK is initialized with an OAuth config (
clientId,redirectUri,scope: "atproto") but then usessdk.restoreSession("did:plc:evaluator123")instead of completing the OAuth flow withsdk.callback(callbackParams). These are distinct authentication flows:
- OAuth flow →
sdk.authorize(identifier)→sdk.callback(callbackParams)to obtain session- Session restore →
sdk.restoreSession(did)to load a previously persisted sessionThe OAuth config will not be used by
restoreSession(), making it misleading. Readers copying this snippet will not understand which authentication method to use, or will not realize thatrestoreSession()requires a persisted session from the SessionStore.Either remove the OAuth config and use app-password/server-side authentication (which works with
restoreSession()), or replacerestoreSession()withsdk.callback(callbackParams)to complete the OAuth flow shown in the config.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/getting-started/working-with-evaluations.md` around lines 13 - 34, The snippet mixes OAuth configuration with a session-restore call: the createATProtoSDK oauth block will not be used if you call sdk.restoreSession("did:plc:evaluator123"); either remove the oauth config and document that restoreSession expects a previously persisted session (SessionStore/app-password style), or keep the oauth config and replace the restoreSession call with the OAuth flow (call sdk.authorize(identifier) then complete with sdk.callback(callbackParams) to obtain the session) so the example consistently uses one authentication method (refer to createATProtoSDK, oauth, sdk.restoreSession, sdk.authorize, and sdk.callback).
🧹 Nitpick comments (4)
pages/lexicons/certified-lexicons/shared-defs.md (1)
23-29: Consider adding a short description for theapp.certified.defssection.The new section drops straight into the table. A one-sentence note explaining the relationship between
app.certified.defsandorg.hypercerts.defs(e.g., that the former is used by Certified-namespace lexicons) would help readers orient.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/certified-lexicons/shared-defs.md` around lines 23 - 29, Add a one-sentence descriptive note under the "Certified Definitions" heading explaining the role of app.certified.defs and its relationship to org.hypercerts.defs (for example: "app.certified.defs defines shared types used by Certified-namespace lexicons and extends/aligns with common types from org.hypercerts.defs"). Place this sentence immediately before the table so readers understand that app.certified.defs contains definitions used by Certified lexicons and how it relates to org.hypercerts.defs.pages/tools/sdk.md (1)
259-272: Missing import forcreateATProtoSDKin the local development example.Unlike the React hooks example above it, this snippet doesn't show the import, so readers don't know which package to import from. Every other runnable snippet in this file shows its imports.
🛠️ Proposed fix
+import { createATProtoSDK } from "@hypercerts-org/sdk-core"; + const sdk = createATProtoSDK({ oauth: {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/tools/sdk.md` around lines 259 - 272, Add the missing import for createATProtoSDK at the top of the example so the snippet is runnable; import the factory from the SDK package (e.g., import { createATProtoSDK } from '@atproto/sdk') and ensure the import style matches the React hooks example and other snippets in the file so readers know which package to import from.pages/lexicons/certified-lexicons/badge-response.md (1)
21-21: Add a note clarifyingweightis only meaningful whenresponseisaccepted.The Comments cell is empty; a rejected badge award with a non-null
weightis semantically ambiguous.✏️ Suggested wording
-| `weight` | `string` | ❌ | Optional relative weight for accepted badges, assigned by the recipient | | +| `weight` | `string` | ❌ | Optional relative weight for accepted badges, assigned by the recipient | Only meaningful when `response` is `accepted`. |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/certified-lexicons/badge-response.md` at line 21, Update the badge-response documentation to clarify that the `weight` field is only meaningful when `response` equals `accepted`; specifically, modify the table row for `weight` (the `weight` column entry) to add a comment noting that `weight` should be set only for accepted responses and is ignored or semantically invalid for `rejected` responses, and ensure the `response` field is referenced so readers understand the conditional relationship between `weight` and `response`.pages/lexicons/hypercerts-lexicons/funding-receipt.md (1)
41-70: Code example uses the low-level@atproto/apirather than the Hypercerts SDK.Every other example in this PR (
quickstart.md,building-on-hypercerts.md, etc.) uses@hypercerts-org/sdk-core. UsingBskyAgentdirectly here is inconsistent and sends mixed signals to readers. If funding receipts aren't yet exposed by the SDK, consider updating the callout to explicitly note that SDK support is coming and this is a temporary raw-API approach, or add the receipt to the SDK surface before publishing.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md` around lines 41 - 70, The example uses the low-level BskyAgent and agent.api.com.atproto.repo.createRecord to publish an org.hypercerts.funding.receipt, which is inconsistent with other docs that use `@hypercerts-org/sdk-core`; either update this sample to call the SDK equivalent (use the SDK client method that publishes receipts—replace BskyAgent usage with the SDK client initializer and its publish/createReceipt method) or, if the SDK does not yet support funding receipts, add a clear callout above the snippet stating this is a temporary raw-API workaround and that SDK support for org.hypercerts.funding.receipt will be added soon. Ensure you reference BskyAgent, agent.api.com.atproto.repo.createRecord, and org.hypercerts.funding.receipt in the change so reviewers can find and update the snippet or add the callout.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/architecture/data-flow-and-lifecycle.md`:
- Line 22: Update the wording in pages/architecture/data-flow-and-lifecycle.md:
replace the phrase "this works today on ATProto" with "this works today on AT
Protocol" to match the PR-wide rename; ensure the surrounding sentence remains
unchanged and only the token "ATProto" in the Funding paragraph is updated.
In `@pages/architecture/indexers-and-discovery.md`:
- Around line 42-44: The current docs recommend Constellation without warning
readers that its API is unstable; edit the paragraph describing Constellation
(the block that begins "Constellation indexes ATProto records...") to add a
short stability caveat noting the API is unstable and may change (e.g., a
one-sentence note or the suggested italicized note "_Note: Constellation's API
is under active development and may change._") so readers know not to rely on it
for production guarantees.
In `@pages/core-concepts/funding-and-value-flow.md`:
- Line 59: Replace the outdated abbreviation "ATProto" with the new canonical
name "AT Protocol" in the sentence that currently reads "the canonical record
remains the ATProto data" — update that phrase to "the canonical record remains
the AT Protocol data" (search for the exact phrase "the canonical record remains
the ATProto data" to locate the change and ensure consistency with other files
using "AT Protocol").
In `@pages/getting-started/creating-your-first-hypercert.md`:
- Around line 125-134: The "What you've built" tree is inconsistent with the
create() call that uses plain DID strings (the contributors:
["did:plc:alice123"] array in the create() invocation); either simplify the
diagram to show Contributors as DID entries (no ContributorInformation child
records) or add explicit creation of ContributorInformation records before the
create() call and replace the plain DID strings with the returned record DIDs;
locate the create() usage and the "What you've built" tree text, then either (A)
update the tree to reflect plain DID contributors, or (B) insert steps to create
contributorInformation records (e.g., createContributorInformation /
contributorInformation.create or similar) and use their DIDs in the contributors
array so the tree matches the actual structure.
In `@pages/getting-started/testing-and-deployment.md`:
- Around line 63-67: Update the prose to use the correct field name shown in the
example logs: replace the backticked `cid` with `hypercertCid` and optionally
mention `result.hypercertCid` to match the code that logs `result.hypercertCid`
(the surrounding example also logs `result.hypercertUri`, so ensure only the CID
reference is renamed to `hypercertCid`).
In `@pages/lexicons/hypercerts-lexicons/acknowledgement.md`:
- Around line 29-62: Update the example to be consistent with the PR: either (A)
replace the `@atproto/api` app-password example (BskyAgent + agent.login) with the
OAuth pattern used elsewhere (use createATProtoSDK / sdk.getRepository /
repo.records.create and the jwkPrivate OAuth flow) and change the callout to
scope the warning to "The Hypercerts SDK is in active development", or (B) if
you must keep the low-level `@atproto/api` snippet, change the callout to clearly
state that the warning applies only to the Hypercerts SDK and not to
`@atproto/api`, and change agent.login(...) to the OAuth flow used across the PR
for consistency; update the callout text accordingly and ensure unique
identifiers (BskyAgent, agent.login, createATProtoSDK, sdk.getRepository,
repo.records.create) are used to locate and modify the snippet.
In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md`:
- Around line 17-19: The table entry for the `from` property currently marks it
as Required (✅) but the comments and examples allow omission for anonymous
funding; update the `from` property row in the lexicon table to mark it as
Optional (change the Required column from ✅ to ❌) so the documentation matches
the anonymous-sender behavior described in the comments and examples for the
`from` field.
In `@pages/tools/sdk.md`:
- Around line 115-130: The snippet places JSX (the
QueryClientProvider/WagmiProvider/atproto.Provider tree) at top-level after
TypeScript statements, causing invalid TSX; wrap the example in a valid React
component or render function (e.g., create a functional component like function
AppRoot() { const queryClient = new QueryClient(); const atproto =
createATProtoReact({ config, queryClient }); return ( <QueryClientProvider
client={queryClient}> <WagmiProvider config={wagmiConfig}> <atproto.Provider>
<App /> </atproto.Provider> </WagmiProvider> </QueryClientProvider> ); } or show
usage via ReactDOM.render/ createRoot) so QueryClient, createATProtoReact,
QueryClientProvider, WagmiProvider, atproto.Provider and App appear inside a
return body rather than at top-level.
---
Outside diff comments:
In `@pages/getting-started/working-with-evaluations.md`:
- Around line 13-34: The snippet mixes OAuth configuration with a
session-restore call: the createATProtoSDK oauth block will not be used if you
call sdk.restoreSession("did:plc:evaluator123"); either remove the oauth config
and document that restoreSession expects a previously persisted session
(SessionStore/app-password style), or keep the oauth config and replace the
restoreSession call with the OAuth flow (call sdk.authorize(identifier) then
complete with sdk.callback(callbackParams) to obtain the session) so the example
consistently uses one authentication method (refer to createATProtoSDK, oauth,
sdk.restoreSession, sdk.authorize, and sdk.callback).
---
Nitpick comments:
In `@pages/lexicons/certified-lexicons/badge-response.md`:
- Line 21: Update the badge-response documentation to clarify that the `weight`
field is only meaningful when `response` equals `accepted`; specifically, modify
the table row for `weight` (the `weight` column entry) to add a comment noting
that `weight` should be set only for accepted responses and is ignored or
semantically invalid for `rejected` responses, and ensure the `response` field
is referenced so readers understand the conditional relationship between
`weight` and `response`.
In `@pages/lexicons/certified-lexicons/shared-defs.md`:
- Around line 23-29: Add a one-sentence descriptive note under the "Certified
Definitions" heading explaining the role of app.certified.defs and its
relationship to org.hypercerts.defs (for example: "app.certified.defs defines
shared types used by Certified-namespace lexicons and extends/aligns with common
types from org.hypercerts.defs"). Place this sentence immediately before the
table so readers understand that app.certified.defs contains definitions used by
Certified lexicons and how it relates to org.hypercerts.defs.
In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md`:
- Around line 41-70: The example uses the low-level BskyAgent and
agent.api.com.atproto.repo.createRecord to publish an
org.hypercerts.funding.receipt, which is inconsistent with other docs that use
`@hypercerts-org/sdk-core`; either update this sample to call the SDK equivalent
(use the SDK client method that publishes receipts—replace BskyAgent usage with
the SDK client initializer and its publish/createReceipt method) or, if the SDK
does not yet support funding receipts, add a clear callout above the snippet
stating this is a temporary raw-API workaround and that SDK support for
org.hypercerts.funding.receipt will be added soon. Ensure you reference
BskyAgent, agent.api.com.atproto.repo.createRecord, and
org.hypercerts.funding.receipt in the change so reviewers can find and update
the snippet or add the callout.
In `@pages/tools/sdk.md`:
- Around line 259-272: Add the missing import for createATProtoSDK at the top of
the example so the snippet is runnable; import the factory from the SDK package
(e.g., import { createATProtoSDK } from '@atproto/sdk') and ensure the import
style matches the React hooks example and other snippets in the file so readers
know which package to import from.
- Replace 'ATProto' with 'AT Protocol' in prose (data-flow, funding-and-value-flow, indexers) - Add Constellation API stability caveat in indexers-and-discovery - Fix stale field name: cid → hypercertCid in testing-and-deployment - Fix funding-receipt from field: required → optional (matches lexicon) - Fix Wagmi snippet: wrap JSX in function component, use tsx language tag - Simplify tree diagram in creating-your-first-hypercert to match code - Update all 9 lexicon page callouts to clarify low-level API usage
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (4)
pages/getting-started/creating-your-first-hypercert.md (1)
58-62: Clarify that this is an alternative create path, not the next sequential step.This section reads like a continuation, but it performs another
create()and reusesresult, which can imply creating a duplicate hypercert in a step-by-step run. Consider explicitly labeling this as an alternative example (or renaming the variable in this block) to avoid flow confusion.Also applies to: 93-101
🤖 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` around lines 58 - 62, This section should be marked as an alternative create path rather than a continuation: update the surrounding copy to say "Alternative: include contributors directly" (or similar) and change the example variable from result to a distinct name (e.g., resultWithContributors) so it doesn't imply a sequential reuse; apply the same change to the later create() example that also reuses result (the repo.hypercerts.create snippets) to avoid suggesting duplicate creation in a step-by-step run.pages/lexicons/hypercerts-lexicons/acknowledgement.md (1)
23-23: Optional: Consider simplifying "originally created" to "created".The phrase "originally created" in the
createdAtfield description is slightly redundant — "created" alone conveys the same meaning. However, this phrasing is common in API documentation and perfectly acceptable.✏️ Optional simplification
-| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | Format: `datetime`. | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was created | Format: `datetime`. |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/hypercerts-lexicons/acknowledgement.md` at line 23, The description for the `createdAt` field is slightly redundant—replace the phrase "Client-declared timestamp when this record was originally created" with a simpler "Client-declared timestamp when this record was created" in the acknowledgement.md table so the meaning remains identical but wording is cleaner; update the cell associated with `createdAt` to use "created" instead of "originally created".pages/tools/sdk.md (1)
24-37: Add a language identifier to the fenced code block.The ASCII diagram should specify a language (e.g.,
textorplaintext) to satisfy linting rules and improve accessibility for screen readers.📝 Suggested fix
-``` +```text ┌─────────────────────────────────────────────────┐ │ Your Application │🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/tools/sdk.md` around lines 24 - 37, Add a language identifier to the fenced ASCII diagram in pages/tools/sdk.md by changing the opening triple-backtick to include a plain text language (e.g., ```text or ```plaintext) so the code block is lint-friendly and accessible; update the fenced block that contains the ASCII box (the diagram starting with "┌─────────────────────────────────────────────────┐") to use the chosen language identifier.pages/lexicons/hypercerts-lexicons/funding-receipt.md (1)
51-52: Clarify the optionalfromfield in the example.The comment on line 51 states "omit for anonymous funding," but line 52 immediately includes the
fromfield. This could confuse developers implementing anonymous funding receipts.💡 Suggested improvement
Consider demonstrating omission more clearly:
record: { - // DID of the funder (omit for anonymous funding) - from: 'did:plc:funder123', + // DID of the funder — omit this line entirely for anonymous funding + from: 'did:plc:funder123', // Remove this line for anonymous receipts // Recipient — DID or clear-text name to: 'did:plc:recipient456',Or show both patterns in separate examples.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md` around lines 51 - 52, Update the example to clarify that the "from" field is optional for anonymous funding by either removing the from: 'did:plc:funder123' entry from this anonymous example or add a second example block that explicitly shows the non-anonymous pattern with from: 'did:plc:funder123'; ensure you reference the same "from" field in the funding receipt example so readers can see both the omitted (anonymous) and included (identified) variants.
🤖 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 131: The task description contains contradictory file instructions
mentioning a modification to documentation/lib/navigation.js and also saying no
changes are needed; fix the task text to be consistent by removing the
misleading "modify" note for navigation.js and consolidating the file list to
only include creation of documentation/pages/drafts/example-draft.md (and
explicitly state that documentation/lib/navigation.js, Layout.js, and Sidebar.js
must NOT be modified); update the description to clearly state acceptance
criteria (file exists with draft: true, accessible at /drafts/example-draft, not
in sidebar, no prev/next links) so reviewers and CI validate the single intended
change.
- Line 130: The issue title currently mentions "in dev mode" but the description
and acceptance criteria require the banner to appear in both dev and production;
update the title for the issue with id "hypercerts-atproto-documentation-qu1.3"
to remove the "in dev mode" wording (e.g., change to "Show DRAFT banner on draft
pages") so it matches the task details and acceptance criteria; ensure the rest
of the JSON (description, acceptance_criteria, and status) remains unchanged.
In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md`:
- Line 24: Update the example value in the funding-receipt lexicon row for
`paymentNetwork` to use correct brand capitalization: replace the lowercase
"paypal" with "PayPal" in the example list (`arbitrum`, `ethereum`, `sepa`,
`visa`, `paypal` → `arbitrum`, `ethereum`, `sepa`, `visa`, `PayPal`) so the
`paymentNetwork` documentation uses the official brand spelling.
---
Nitpick comments:
In `@pages/getting-started/creating-your-first-hypercert.md`:
- Around line 58-62: This section should be marked as an alternative create path
rather than a continuation: update the surrounding copy to say "Alternative:
include contributors directly" (or similar) and change the example variable from
result to a distinct name (e.g., resultWithContributors) so it doesn't imply a
sequential reuse; apply the same change to the later create() example that also
reuses result (the repo.hypercerts.create snippets) to avoid suggesting
duplicate creation in a step-by-step run.
In `@pages/lexicons/hypercerts-lexicons/acknowledgement.md`:
- Line 23: The description for the `createdAt` field is slightly
redundant—replace the phrase "Client-declared timestamp when this record was
originally created" with a simpler "Client-declared timestamp when this record
was created" in the acknowledgement.md table so the meaning remains identical
but wording is cleaner; update the cell associated with `createdAt` to use
"created" instead of "originally created".
In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md`:
- Around line 51-52: Update the example to clarify that the "from" field is
optional for anonymous funding by either removing the from: 'did:plc:funder123'
entry from this anonymous example or add a second example block that explicitly
shows the non-anonymous pattern with from: 'did:plc:funder123'; ensure you
reference the same "from" field in the funding receipt example so readers can
see both the omitted (anonymous) and included (identified) variants.
In `@pages/tools/sdk.md`:
- Around line 24-37: Add a language identifier to the fenced ASCII diagram in
pages/tools/sdk.md by changing the opening triple-backtick to include a plain
text language (e.g., ```text or ```plaintext) so the code block is lint-friendly
and accessible; update the fenced block that contains the ASCII box (the diagram
starting with "┌─────────────────────────────────────────────────┐") to use the
chosen language identifier.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (19)
.beads/issues.jsonllib/navigation.jspages/architecture/data-flow-and-lifecycle.mdpages/architecture/indexers-and-discovery.mdpages/core-concepts/funding-and-value-flow.mdpages/getting-started/creating-your-first-hypercert.mdpages/getting-started/testing-and-deployment.mdpages/index.mdpages/lexicons/hypercerts-lexicons/acknowledgement.mdpages/lexicons/hypercerts-lexicons/activity-claim.mdpages/lexicons/hypercerts-lexicons/attachment.mdpages/lexicons/hypercerts-lexicons/collection.mdpages/lexicons/hypercerts-lexicons/contribution.mdpages/lexicons/hypercerts-lexicons/evaluation.mdpages/lexicons/hypercerts-lexicons/funding-receipt.mdpages/lexicons/hypercerts-lexicons/measurement.mdpages/lexicons/hypercerts-lexicons/rights.mdpages/tools/hyperboards.mdpages/tools/sdk.md
✅ Files skipped from review due to trivial changes (1)
- pages/lexicons/hypercerts-lexicons/collection.md
🚧 Files skipped from review as they are similar to previous changes (2)
- pages/getting-started/testing-and-deployment.md
- pages/tools/hyperboards.md
| {"id":"hypercerts-atproto-documentation-qu1","title":"Epic: Draft pages system — unlisted pages with /drafts index","description":"Add a draft page system to the documentation site. Pages with `draft: true` in frontmatter should be excluded from the sidebar navigation and prev/next pagination, but remain accessible by direct URL. A /drafts index page lists all draft pages so devs can find them. This lets the team write documentation ahead of time without exposing it to public visitors. Success: draft pages are invisible in sidebar/pagination, accessible by URL, and discoverable at /drafts.","status":"open","priority":2,"issue_type":"epic","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-23T16:52:19.61403+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:11:42.24997+08:00","labels":["needs-integration-review","scope:medium"]} | ||
| {"id":"hypercerts-atproto-documentation-qu1.1","title":"Add getDraftPages() utility to lib/navigation.js","description":"## Files\n- documentation/lib/navigation.js (modify)\n\n## What to do\nAdd a new exported function `getDraftPages()` that:\n1. Uses Node.js `fs` and `path` to recursively scan `pages/` directory for `.md` and `.mdoc` files\n2. Reads the frontmatter of each file (parse YAML between `---` fences)\n3. Returns an array of `{ title, path, description }` for files where `draft: true` is in frontmatter\n4. The `path` should be the URL path (e.g., `pages/drafts/my-page.md` → `/drafts/my-page`)\n\nIMPORTANT: This function will only be called at build time (in getStaticProps), so using `fs` is fine. Do NOT import `fs` at the top level — use dynamic require inside the function body so it does not break client-side bundles.\n\nExample return value:\n```js\n[\n { title: \"Token Bridge Design\", path: \"/drafts/token-bridge\", description: \"Early design notes...\" },\n { title: \"Governance Model\", path: \"/architecture/governance\", description: undefined }\n]\n```\n\n## Don't\n- Import fs/path at the module top level (breaks client bundle)\n- Modify the existing `navigation`, `flattenNavigation`, or `getPrevNext` exports\n- Add any npm dependencies","acceptance_criteria":"1. `getDraftPages()` is exported from `lib/navigation.js`\n2. It returns an array of objects with `title`, `path`, and `description` keys\n3. It only includes pages where frontmatter has `draft: true`\n4. It does NOT include pages where `draft` is missing or `false`\n5. The path values are correct URL paths (no `.md` extension, no `pages/` prefix, `index.md` maps to parent dir)\n6. No top-level `fs` or `path` import exists in the file\n7. Existing exports (`navigation`, `flattenNavigation`, `getPrevNext`) still work unchanged","status":"closed","priority":2,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","estimated_minutes":30,"created_at":"2026-02-23T16:52:36.411067+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:04:55.059341+08:00","closed_at":"2026-02-23T17:04:55.059341+08:00","close_reason":"e03fb4a Add getDraftPages() utility function","labels":["scope:small"],"dependencies":[{"issue_id":"hypercerts-atproto-documentation-qu1.1","depends_on_id":"hypercerts-atproto-documentation-qu1","type":"parent-child","created_at":"2026-02-23T16:52:36.411868+08:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"hypercerts-atproto-documentation-qu1.2","title":"Create /drafts index page","description":"## Files\n- documentation/pages/drafts/index.js (create)\n\n## What to do\nCreate a Next.js page at `/drafts` that lists all draft pages. This is a `.js` page (not `.md`) because it needs `getStaticProps` to call `getDraftPages()`.\n\nThe page should:\n1. Import and call `getDraftPages()` from `../../lib/navigation` inside `getStaticProps`\n2. Return the list as a prop\n3. Render a simple page with:\n - Title: \"Draft Pages\" (set via frontmatter-like props so Layout picks it up)\n - A subtitle/description: \"These pages are work-in-progress and not yet listed in the sidebar.\"\n - A list of draft pages, each showing:\n - The page title as a clickable link (use Next.js `Link`)\n - The description underneath (if available), in secondary text color\n - The URL path in small monospace text (so devs can reference it)\n - If no draft pages exist, show a message: \"No draft pages yet.\"\n4. Pass `markdoc: { frontmatter: { title: \"Draft Pages\" } }` in the props so the Layout component picks up the page title correctly\n\nStyle the page using the existing CSS variables and class conventions from globals.css. Use inline styles or a `\u003cstyle jsx\u003e` block — do NOT modify globals.css for this page.\n\n## Don't\n- Use .md/.mdoc format (needs getStaticProps for dynamic content)\n- Add this page to the `navigation` array in lib/navigation.js (it should be unlisted)\n- Modify globals.css\n- Add any npm dependencies","acceptance_criteria":"1. Visiting /drafts in the browser renders a page titled \"Draft Pages\"\n2. The page lists all .md files that have `draft: true` in frontmatter\n3. Each listed page shows its title as a clickable link, optional description, and URL path\n4. Clicking a link navigates to the draft page\n5. The page title appears in the browser tab as \"Draft Pages - Hypercerts Protocol\"\n6. The /drafts page does NOT appear in the sidebar navigation\n7. When no draft pages exist, the message \"No draft pages yet.\" is shown\n8. The page uses the site Layout (header, sidebar visible but /drafts not highlighted)","status":"closed","priority":2,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","estimated_minutes":45,"created_at":"2026-02-23T16:52:53.435836+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:09:18.570394+08:00","closed_at":"2026-02-23T17:09:18.570394+08:00","close_reason":"8951cf5 Create /drafts index page","labels":["scope:small"],"dependencies":[{"issue_id":"hypercerts-atproto-documentation-qu1.2","depends_on_id":"hypercerts-atproto-documentation-qu1","type":"parent-child","created_at":"2026-02-23T16:52:53.436646+08:00","created_by":"sharfy-test.climateai.org"},{"issue_id":"hypercerts-atproto-documentation-qu1.2","depends_on_id":"hypercerts-atproto-documentation-qu1.1","type":"blocks","created_at":"2026-02-23T16:52:53.437875+08:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"hypercerts-atproto-documentation-qu1.3","title":"Show DRAFT banner on draft pages in dev mode","description":"## Files\n- documentation/components/Layout.js (modify)\n\n## What to do\nWhen a page has `draft: true` in its frontmatter, show a visible banner at the top of the article content area. This helps devs immediately see they are viewing a draft page.\n\nThe banner should:\n1. Check `frontmatter?.draft === true`\n2. Render a yellow/amber banner above the `\u003carticle\u003e` element (but below the Breadcrumbs)\n3. Banner text: \"📝 This page is a draft and is not listed in the sidebar navigation.\"\n4. Style: amber/yellow background (`#fef3c7`), dark amber text (`#92400e`), 1px border (`#fcd34d`), rounded corners, padding, `font-size: 14px`, `font-weight: 500`\n5. Use inline styles on the banner div (do NOT modify globals.css)\n\nThe banner should show in BOTH dev and production — it is useful for anyone who navigates to the URL directly.\n\n## Don't\n- Modify globals.css\n- Modify any other component\n- Change how frontmatter is passed (it is already available as the `frontmatter` prop)\n- Add any conditional logic based on NODE_ENV (show the banner always)","acceptance_criteria":"1. Pages with `draft: true` frontmatter show a yellow banner reading \"📝 This page is a draft and is not listed in the sidebar navigation.\"\n2. Pages without `draft: true` do NOT show the banner\n3. The banner appears between the Breadcrumbs and the article content\n4. The banner has amber/yellow styling (background #fef3c7, text #92400e, border #fcd34d)\n5. No changes to globals.css\n6. Existing pages render exactly as before (no visual regression)","status":"closed","priority":3,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","estimated_minutes":15,"created_at":"2026-02-23T16:53:07.104334+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:01:51.204858+08:00","closed_at":"2026-02-23T17:01:51.204858+08:00","close_reason":"42ad0d0 Show DRAFT banner on draft pages","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-atproto-documentation-qu1.3","depends_on_id":"hypercerts-atproto-documentation-qu1","type":"parent-child","created_at":"2026-02-23T16:53:07.105221+08:00","created_by":"sharfy-test.climateai.org"}]} |
There was a problem hiding this comment.
Title scope conflicts with task requirements
Line 130 says “in dev mode,” but the description and acceptance criteria explicitly require behavior in both development and production. Please align the title to avoid ambiguity in planning/reporting.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.beads/issues.jsonl at line 130, The issue title currently mentions "in dev
mode" but the description and acceptance criteria require the banner to appear
in both dev and production; update the title for the issue with id
"hypercerts-atproto-documentation-qu1.3" to remove the "in dev mode" wording
(e.g., change to "Show DRAFT banner on draft pages") so it matches the task
details and acceptance criteria; ensure the rest of the JSON (description,
acceptance_criteria, and status) remains unchanged.
| {"id":"hypercerts-atproto-documentation-qu1.1","title":"Add getDraftPages() utility to lib/navigation.js","description":"## Files\n- documentation/lib/navigation.js (modify)\n\n## What to do\nAdd a new exported function `getDraftPages()` that:\n1. Uses Node.js `fs` and `path` to recursively scan `pages/` directory for `.md` and `.mdoc` files\n2. Reads the frontmatter of each file (parse YAML between `---` fences)\n3. Returns an array of `{ title, path, description }` for files where `draft: true` is in frontmatter\n4. The `path` should be the URL path (e.g., `pages/drafts/my-page.md` → `/drafts/my-page`)\n\nIMPORTANT: This function will only be called at build time (in getStaticProps), so using `fs` is fine. Do NOT import `fs` at the top level — use dynamic require inside the function body so it does not break client-side bundles.\n\nExample return value:\n```js\n[\n { title: \"Token Bridge Design\", path: \"/drafts/token-bridge\", description: \"Early design notes...\" },\n { title: \"Governance Model\", path: \"/architecture/governance\", description: undefined }\n]\n```\n\n## Don't\n- Import fs/path at the module top level (breaks client bundle)\n- Modify the existing `navigation`, `flattenNavigation`, or `getPrevNext` exports\n- Add any npm dependencies","acceptance_criteria":"1. `getDraftPages()` is exported from `lib/navigation.js`\n2. It returns an array of objects with `title`, `path`, and `description` keys\n3. It only includes pages where frontmatter has `draft: true`\n4. It does NOT include pages where `draft` is missing or `false`\n5. The path values are correct URL paths (no `.md` extension, no `pages/` prefix, `index.md` maps to parent dir)\n6. No top-level `fs` or `path` import exists in the file\n7. Existing exports (`navigation`, `flattenNavigation`, `getPrevNext`) still work unchanged","status":"closed","priority":2,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","estimated_minutes":30,"created_at":"2026-02-23T16:52:36.411067+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:04:55.059341+08:00","closed_at":"2026-02-23T17:04:55.059341+08:00","close_reason":"e03fb4a Add getDraftPages() utility function","labels":["scope:small"],"dependencies":[{"issue_id":"hypercerts-atproto-documentation-qu1.1","depends_on_id":"hypercerts-atproto-documentation-qu1","type":"parent-child","created_at":"2026-02-23T16:52:36.411868+08:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"hypercerts-atproto-documentation-qu1.2","title":"Create /drafts index page","description":"## Files\n- documentation/pages/drafts/index.js (create)\n\n## What to do\nCreate a Next.js page at `/drafts` that lists all draft pages. This is a `.js` page (not `.md`) because it needs `getStaticProps` to call `getDraftPages()`.\n\nThe page should:\n1. Import and call `getDraftPages()` from `../../lib/navigation` inside `getStaticProps`\n2. Return the list as a prop\n3. Render a simple page with:\n - Title: \"Draft Pages\" (set via frontmatter-like props so Layout picks it up)\n - A subtitle/description: \"These pages are work-in-progress and not yet listed in the sidebar.\"\n - A list of draft pages, each showing:\n - The page title as a clickable link (use Next.js `Link`)\n - The description underneath (if available), in secondary text color\n - The URL path in small monospace text (so devs can reference it)\n - If no draft pages exist, show a message: \"No draft pages yet.\"\n4. Pass `markdoc: { frontmatter: { title: \"Draft Pages\" } }` in the props so the Layout component picks up the page title correctly\n\nStyle the page using the existing CSS variables and class conventions from globals.css. Use inline styles or a `\u003cstyle jsx\u003e` block — do NOT modify globals.css for this page.\n\n## Don't\n- Use .md/.mdoc format (needs getStaticProps for dynamic content)\n- Add this page to the `navigation` array in lib/navigation.js (it should be unlisted)\n- Modify globals.css\n- Add any npm dependencies","acceptance_criteria":"1. Visiting /drafts in the browser renders a page titled \"Draft Pages\"\n2. The page lists all .md files that have `draft: true` in frontmatter\n3. Each listed page shows its title as a clickable link, optional description, and URL path\n4. Clicking a link navigates to the draft page\n5. The page title appears in the browser tab as \"Draft Pages - Hypercerts Protocol\"\n6. The /drafts page does NOT appear in the sidebar navigation\n7. When no draft pages exist, the message \"No draft pages yet.\" is shown\n8. The page uses the site Layout (header, sidebar visible but /drafts not highlighted)","status":"closed","priority":2,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","estimated_minutes":45,"created_at":"2026-02-23T16:52:53.435836+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:09:18.570394+08:00","closed_at":"2026-02-23T17:09:18.570394+08:00","close_reason":"8951cf5 Create /drafts index page","labels":["scope:small"],"dependencies":[{"issue_id":"hypercerts-atproto-documentation-qu1.2","depends_on_id":"hypercerts-atproto-documentation-qu1","type":"parent-child","created_at":"2026-02-23T16:52:53.436646+08:00","created_by":"sharfy-test.climateai.org"},{"issue_id":"hypercerts-atproto-documentation-qu1.2","depends_on_id":"hypercerts-atproto-documentation-qu1.1","type":"blocks","created_at":"2026-02-23T16:52:53.437875+08:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"hypercerts-atproto-documentation-qu1.3","title":"Show DRAFT banner on draft pages in dev mode","description":"## Files\n- documentation/components/Layout.js (modify)\n\n## What to do\nWhen a page has `draft: true` in its frontmatter, show a visible banner at the top of the article content area. This helps devs immediately see they are viewing a draft page.\n\nThe banner should:\n1. Check `frontmatter?.draft === true`\n2. Render a yellow/amber banner above the `\u003carticle\u003e` element (but below the Breadcrumbs)\n3. Banner text: \"📝 This page is a draft and is not listed in the sidebar navigation.\"\n4. Style: amber/yellow background (`#fef3c7`), dark amber text (`#92400e`), 1px border (`#fcd34d`), rounded corners, padding, `font-size: 14px`, `font-weight: 500`\n5. Use inline styles on the banner div (do NOT modify globals.css)\n\nThe banner should show in BOTH dev and production — it is useful for anyone who navigates to the URL directly.\n\n## Don't\n- Modify globals.css\n- Modify any other component\n- Change how frontmatter is passed (it is already available as the `frontmatter` prop)\n- Add any conditional logic based on NODE_ENV (show the banner always)","acceptance_criteria":"1. Pages with `draft: true` frontmatter show a yellow banner reading \"📝 This page is a draft and is not listed in the sidebar navigation.\"\n2. Pages without `draft: true` do NOT show the banner\n3. The banner appears between the Breadcrumbs and the article content\n4. The banner has amber/yellow styling (background #fef3c7, text #92400e, border #fcd34d)\n5. No changes to globals.css\n6. Existing pages render exactly as before (no visual regression)","status":"closed","priority":3,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","estimated_minutes":15,"created_at":"2026-02-23T16:53:07.104334+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:01:51.204858+08:00","closed_at":"2026-02-23T17:01:51.204858+08:00","close_reason":"42ad0d0 Show DRAFT banner on draft pages","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-atproto-documentation-qu1.3","depends_on_id":"hypercerts-atproto-documentation-qu1","type":"parent-child","created_at":"2026-02-23T16:53:07.105221+08:00","created_by":"sharfy-test.climateai.org"}]} | ||
| {"id":"hypercerts-atproto-documentation-qu1.4","title":"Exclude draft pages from prev/next pagination","description":"## Files\n- documentation/lib/navigation.js (modify)\n\n## What to do\nCurrently `flattenNavigation()` and `getPrevNext()` operate on the manual `navigation` array, which only contains non-draft pages. This is already correct — draft pages are not in the `navigation` array, so they will never appear in prev/next links.\n\nHowever, when a user is ON a draft page, `getPrevNext()` will return `{ prev: null, next: null }` because the draft page path won't be found in the flat list. This is the desired behavior — draft pages should not show prev/next pagination.\n\n**No code changes needed for navigation.js.** The task is to verify this behavior and ensure the Layout handles the case gracefully (it already does — pagination is conditionally rendered with `{(prev || next) \u0026\u0026 ...}`).\n\nThe real work: create a sample draft page to test the system end-to-end.\n\n## Files\n- documentation/pages/drafts/example-draft.md (create)\n\nCreate a sample draft page at `pages/drafts/example-draft.md` with this content:\n\n```markdown\n---\ntitle: Example Draft Page\ndescription: This is a sample draft page to verify the draft system works.\ndraft: true\n---\n\n# Example Draft Page\n\nThis page exists to verify the draft system. It should:\n\n- ✅ Be accessible at `/drafts/example-draft`\n- ✅ NOT appear in the sidebar navigation\n- ✅ NOT appear in prev/next pagination\n- ✅ Show a draft banner (if that task is complete)\n- ✅ Be listed on the `/drafts` index page (if that task is complete)\n\n## Sample content\n\nThis is placeholder content for testing purposes. Replace or remove this page when real draft content is added.\n```\n\n## Don't\n- Modify navigation.js (the behavior is already correct)\n- Add the example draft page to the navigation array\n- Modify Layout.js or Sidebar.js","acceptance_criteria":"1. The file `pages/drafts/example-draft.md` exists with `draft: true` in frontmatter\n2. Visiting `/drafts/example-draft` renders the page with its content\n3. The page does NOT appear in the sidebar navigation\n4. The page does NOT show prev/next pagination links\n5. The navigation array in lib/navigation.js is unchanged","status":"closed","priority":2,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","estimated_minutes":10,"created_at":"2026-02-23T16:53:22.058897+08:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-23T17:00:44.51411+08:00","closed_at":"2026-02-23T17:00:44.51411+08:00","close_reason":"a09a1f5 Add example draft page for testing draft system","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-atproto-documentation-qu1.4","depends_on_id":"hypercerts-atproto-documentation-qu1","type":"parent-child","created_at":"2026-02-23T16:53:22.060017+08:00","created_by":"sharfy-test.climateai.org"}]} |
There was a problem hiding this comment.
Conflicting file instructions in task description
Line 131 has contradictory guidance: it lists documentation/lib/navigation.js as modified, then states no navigation changes are needed, and includes a second ## Files block. Consolidating this into one consistent file list will reduce execution and validation confusion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.beads/issues.jsonl at line 131, The task description contains contradictory
file instructions mentioning a modification to documentation/lib/navigation.js
and also saying no changes are needed; fix the task text to be consistent by
removing the misleading "modify" note for navigation.js and consolidating the
file list to only include creation of
documentation/pages/drafts/example-draft.md (and explicitly state that
documentation/lib/navigation.js, Layout.js, and Sidebar.js must NOT be
modified); update the description to clearly state acceptance criteria (file
exists with draft: true, accessible at /drafts/example-draft, not in sidebar, no
prev/next links) so reviewers and CI validate the single intended change.
| | `amount` | `string` | ✅ | Amount of funding received | | | ||
| | `currency` | `string` | ✅ | Currency of the payment | E.g. EUR, USD, ETH. | | ||
| | `paymentRail` | `string` | ❌ | How the funds were transferred | E.g. `bank_transfer`, `credit_card`, `onchain`, `cash`, `check`, `payment_processor`. | | ||
| | `paymentNetwork` | `string` | ❌ | Network within the payment rail | E.g. `arbitrum`, `ethereum`, `sepa`, `visa`, `paypal`. | |
There was a problem hiding this comment.
Fix brand capitalization: "paypal" → "PayPal".
The official brand name is "PayPal" with two capital letters.
✏️ Proposed fix
-| `paymentNetwork` | `string` | ❌ | Network within the payment rail | E.g. `arbitrum`, `ethereum`, `sepa`, `visa`, `paypal`. |
+| `paymentNetwork` | `string` | ❌ | Network within the payment rail | E.g. `arbitrum`, `ethereum`, `sepa`, `visa`, `PayPal`. |📝 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
| | `paymentNetwork` | `string` | ❌ | Network within the payment rail | E.g. `arbitrum`, `ethereum`, `sepa`, `visa`, `paypal`. | | |
| | `paymentNetwork` | `string` | ❌ | Network within the payment rail | E.g. `arbitrum`, `ethereum`, `sepa`, `visa`, `PayPal`. | |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~24-~24: The official name of this payment provider is spelled with two capital “P”.
Context: ...arbitrum, ethereum, sepa, visa, paypal. | | transactionId | string | ❌ | ...
(PAYPAL)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md` at line 24, Update the
example value in the funding-receipt lexicon row for `paymentNetwork` to use
correct brand capitalization: replace the lowercase "paypal" with "PayPal" in
the example list (`arbitrum`, `ethereum`, `sepa`, `visa`, `paypal` → `arbitrum`,
`ethereum`, `sepa`, `visa`, `PayPal`) so the `paymentNetwork` documentation uses
the official brand spelling.
Add new core-concepts page explaining CEL expressions for structured, machine-evaluable work scopes. Update the "What you've built" diagram in the first hypercert tutorial to show the full record hierarchy. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
pages/getting-started/creating-your-first-hypercert.md (1)
125-137:⚠️ Potential issue | 🟠 MajorTree diagram misrepresents both the tutorial's output and the data model.
The diagram has three critical inconsistencies:
Shows records not built in this tutorial: Lines 134-136 depict two Measurements and an Evaluation, but this tutorial creates none of these. (Line 145 explicitly states evaluations are future actions by third parties.)
Misrepresents contributor data structure: The tree shows
ContributorInformation: AliceandContributorInformation: Bobas child records, but the code at lines 75 and 80 uses plain DID strings (contributors: ["did:plc:alice123"]). NocontributorInformationrecords are created.Incorrect nesting: The tree depicts each Contributor as a parent with two children (
ContributorInformation+ContributionDetails), but the SDK creates a single contribution record with inlinecontributors,contributionDetails, andweightfields—not separate nested child records.Readers who follow the tutorial will not have built the structure shown.
📋 Proposed tree matching what the tutorial actually builds
Activity Claim (the core record) -├── Contributor 1 -│ ├── ContributorInformation: Alice -│ └── ContributionDetails: Lead author -├── Contributor 2 -│ ├── ContributorInformation: Bob -│ └── ContributionDetails: Technical reviewer -├── Attachment: GitHub repository link -├── Measurement: 12 pages written -├── Measurement: 8,500 words -└── Evaluation: "High-quality documentation" (by Carol) +├── Contribution: Alice (did:plc:alice123), Lead author, weight 70 +├── Contribution: Bob (did:plc:bob456), Technical reviewer, weight 30 +└── Attachment: GitHub repository link🤖 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` around lines 125 - 137, The tree diagram misrepresents the tutorial: replace the current tree with one that matches the SDK objects actually created (no Measurement or Evaluation records and no separate ContributorInformation child records); show a single Activity Claim node that contains contribution entries with inline fields contributors (DID strings, e.g. "did:plc:alice123"), contributionDetails, and weight (matching the contributors, contributionDetails, weight fields used in the code), and remove the nested ContributorInformation nodes so the diagram reflects the single contribution record shape the tutorial builds.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/core-concepts/cel-work-scopes.md`:
- Line 196: The external link to https://certified.ink in the sentence about
`workScopeTag` is broken; update the text that references `workScopeTag` to
either remove the dead link, replace it with a valid authoritative URL, or
correct it to the proper domain if one exists (e.g., a working certified tag
provider), and ensure the sentence still reads naturally — locate the sentence
containing `workScopeTag` in pages/core-concepts/cel-work-scopes.md and edit
that line to remove or substitute the link and adjust surrounding wording as
needed.
---
Duplicate comments:
In `@pages/getting-started/creating-your-first-hypercert.md`:
- Around line 125-137: The tree diagram misrepresents the tutorial: replace the
current tree with one that matches the SDK objects actually created (no
Measurement or Evaluation records and no separate ContributorInformation child
records); show a single Activity Claim node that contains contribution entries
with inline fields contributors (DID strings, e.g. "did:plc:alice123"),
contributionDetails, and weight (matching the contributors, contributionDetails,
weight fields used in the code), and remove the nested ContributorInformation
nodes so the diagram reflects the single contribution record shape the tutorial
builds.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
lib/navigation.jspages/core-concepts/cel-work-scopes.mdpages/getting-started/creating-your-first-hypercert.md
|
|
||
| ## Starter tag vocabulary | ||
|
|
||
| `workScopeTag` records are published as ATProto records that anyone can reference via strong references. [Certified](https://certified.ink) publishes curated tag sets for specific domains. Here's an example for regenerative work: |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the external link to certified.ink is accessible
curl -sI "https://certified.ink" | head -20Repository: hypercerts-org/documentation
Length of output: 54
🏁 Script executed:
#!/bin/bash
# More detailed verification of the certified.ink link
# Try with verbose output and status code
curl -w "HTTP Status: %{http_code}\n" -L -I "https://certified.ink" 2>&1 | head -30
# Also try a simple HEAD request with explicit output
echo "---"
curl -s -L -I "https://certified.ink" 2>&1 | head -30Repository: hypercerts-org/documentation
Length of output: 377
The external link https://certified.ink is broken and does not resolve. The domain cannot be reached (DNS resolution failure). Either remove the link, replace it with a valid reference, or update it to the correct URL if the domain has changed.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/core-concepts/cel-work-scopes.md` at line 196, The external link to
https://certified.ink in the sentence about `workScopeTag` is broken; update the
text that references `workScopeTag` to either remove the dead link, replace it
with a valid authoritative URL, or correct it to the proper domain if one exists
(e.g., a working certified tag provider), and ensure the sentence still reads
naturally — locate the sentence containing `workScopeTag` in
pages/core-concepts/cel-work-scopes.md and edit that line to remove or
substitute the link and adjust surrounding wording as needed.
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
2 participants
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
Aligns documentation with the develop branch SDK and Lexicon APIs, updates architecture pages, adds new reference pages, and fixes review feedback.
SDK & Lexicon alignment (develop branch)
Updated all 6 Get Started pages to match the develop branch SDK and Lexicon APIs:
rightsName/rightsType/rightsDescription→ SDK'sname/type/description$typediscriminators → SDKcontributionsarray ({ contributors, contributionDetails, weight })repo.evaluations.create()→repo.hypercerts.addEvaluation(),repo.measurements.create()→repo.hypercerts.addMeasurement(),repo.attachments.create()→repo.hypercerts.addAttachment()result.uri/result.cid→result.hypercertUri/result.hypercertCid/result.rightsUri/result.rightsCidcreatedAt: SDK sets this automaticallydescriptionfield: missing from most examplesATPROTO_CLIENT_SECRET→ATPROTO_JWK_PRIVATE; proper OAuth loopback config withhandleResolverArchitecture section updates
Updated all 5 Architecture pages:
Architecture stack diagram redesign
Fully redesigned
architecture-stack.svg:PDS / SDSreferenceHyperboards rewrite
Rewrote and renamed
hyperboard.md→hyperboards.mdbased on the actual hyperboards.org product:New pages
tools/sdk.md) — TypeScript SDK reference (packages, React hooks, Repository API, OAuth, type system)Core Concepts improvements
CodeRabbit review fixes (Round 1)
CodeRabbit review fixes (Round 2)
cid→hypercertCid(matches SDK return type)fromfield changed from required to optional (matches lexicon schema)tsx@atproto/apiusage vs SDKOther
Summary by CodeRabbit
New Features
Documentation
Breaking Changes