Repository navigation
docs: rebuild the documentation around the protocol - #164
Merged
Merged
Conversation
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedToo many files! This PR contains 166 files, which is 66 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry. ⚙️ Run configuration
⛔ Files ignored due to path filters (36)
📒 Files selected for processing (166)
You can disable this status message by setting the
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 |
Pin pnpm@12.6.0 through packageManager, import the lockfile from package-lock.json with unchanged resolved versions, and move the baseline-browser-mapping override to pnpm-workspace.yaml. CI and Vercel install with --frozen-lockfile.
Record that all pages are written in this repository and only component changelogs are imported. Retire the ePDS and legacy Hyperindex pages in the migration map and update maintainer docs to pnpm commands.
ePDS is being sunset in favour of Entryway and Hyperindex is no longer maintained. Remove the imported pages, their navigation entries and source registrations, and redirect the old routes and raw Markdown URLs to the canonical documents in their own repositories. Inbound links now point to the same GitHub documents.
Open the docs landing page and Start Here with the hypercerts.org framing: an open protocol connecting projects with those who review, vouch for, and back them. Introduce trust signals, data ownership and portability, the case for a shared language, and Certified as the identity service. Add draft Mermaid diagrams for account-owned records and for trust building over time.
Replace the draft Mermaid chain with a theme-aware SVG step chart based on the hypercerts.org trust timeline, plus responsive cards naming each signal's publisher and record type with links to the Guide pages.
Keep the case for harmonized data without naming an initiative the Foundation has no official partnership with.
Add theme-aware SVG diagrams for account-owned records and portability on Why AT Protocol? and for the records around one activity on A Shared Language. Explain that records are spread across servers as well as accounts, and add links to PDSls and AT Protocol explainers.
Render schema tables at build time from the pinned @hypercerts-org/lexicon package (1.4.1) through lexicon-schema markers, shared by page rendering, search, and raw Markdown. Move Hypercerts and Certified Lexicons up one navigation level and document every record type with an overview, usage, a validated example, usage conventions, and related links. Update the inventory, index pages, and introduction for 1.4.1.
Group Reference into Lexicons, XRPC API, SDK, and Services and tooling subsections with uppercase headings, and add placeholder pages for the unreleased XRPC API and SDK. Retire the Architecture overview in favour of the Guide and redirect its routes. Make category rows single links that open their page and expand, with an inline chevron, aligned headings, and a shallower nested indent.
Show only the Hypercerts logo in the header so it fits on mobile, align it with the sidebar, drop the divider, and center the section navigation on wide screens. Trim the Reference overview to its cards and fix the wording on the services overview.
Rewrite the service pages to one structure, depth, and length: where the service fits, the AT Protocol concept behind it, how it works, one code example for integrators, status and source, and related pages. Add a certified.app page explaining what a Certified account is and where users manage it. Clarify that sign-in runs on ePDS or standard AT Protocol sign-in today and is moving to the Entryway.
Add certified.app with the Certified logo as a client of the account, point both the Entryway and CGS at the same Certified PDSs, and keep one independent PDS without write arrows.
Add an info box saying the API and SDK are in active development and which guides will follow, and describe the integration path in plain language.
Read colours, type, and radius from the design system's tokens through @hypercerts-org/ui-react: rust accent, grey body copy, white, grey, and cream grounds, hairline borders, no shadows, 12px radius, 50px header. Keep dark mode as a documentation-site exception with a matching dark palette. Use the library's Banner, Breadcrumb, Button, Badge, Eyebrow, and Heading; restyle code blocks on the grey ground; and give the landing page a hero with a turning heading and one guilloche.
Grow the glossary to 58 terms covering AT Protocol basics, the services in the stack, and the record types, each linked to its full page. Refresh the FAQ answers, drop the help question, and add seven questions on Certified, account ownership, trust, projects, group accounts, and what can be built today.
kristoferlund
changed the title
Remove the outdated roadmap page, unused images, fonts, components, and Markdoc tags, the Beads files, and AGENTS.md. Add a README, a CI check for broken internal links and anchors, and a Dependabot config that proposes new versions of the Hypercerts lexicon and UI packages.
Rewrite the information architecture note to describe the documentation as it is: sections, the structure of Lexicon and service pages, writing rules, design, ownership, and checks. Link both maintainer notes from the README.
Take hand-typed version numbers and counts out of the page text; the generated version line and the Changes badges carry them. Add a test that validates every Lexicon page example against the installed schemas, and a maintainer checklist of what updates automatically and what needs doing by hand when a Lexicon version, a service, or the design system is released.
LastUpdated appends its line to the article outside React and removes it when the route changes, but only while it is mounted. The landing page unmounted it, so arriving there from a docs page left the previous page's date stranded above the hero. Keep it mounted everywhere and hide the date on the landing page instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The team settled on "Releases" for this section. Rename the section, its navigation and search group, and the link texts, and retitle the three component pages that said "Changelog". Move the pages from /changes to /releases and redirect the old paths, including the raw Markdown ones, in vercel.json. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Title the landing page "Build with Hypercerts", in line with how other developer docs open, and show the Reference links as the same boxed cards as the Guide and Client Integration sections. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A progress update attaches to an activity claim, so the claim comes first after the project profile. The timeline now has seven steps, the cards sit four per row, and the funding record can be published by a funder or a third party. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- SDK and API: describe integrating through them as the plan; neither is released yet. - CGS: members sign in through their PDS today and through the Entryway once it is released. "Hypercerts Entryway" becomes "Entryway", as everywhere else. The ePDS changelog documents the current account infrastructure, not a preceding one. - Certified PDSs: accounts are managed at certified.app; they are created on first sign-in in any app. - Drop "AppView" for the Hypercerts stack: the indexer page describes an indexer, a data plane and an API, and the glossary entry goes. - Hyperindex: the testing guide no longer names it, and the skills table marks its GraphQL API as being retired. - Jetstream keeps the record collections it is configured for. - Protocol: the lexicons together with guidance on how records are used. - Endorsements and funding records stay connected to a project; they live in their publishers' repositories. - Signatures: a platform can add one to show it produced a record, rather than this being the established way. - Vocabulary tag: classifies Hypercerts records, used today by collections and features, matching the schema. - Attachments: can come from the project itself or from anyone else. - American spelling for "organization". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t-check Landing page fixes, Releases rename, Guide timeline, and corrections
This branch was successfully deployed
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.
What this is
A rebuild of the documentation site around the protocol-first direction: explain what Hypercerts is and how its records work before anything else, give builders an accurate reference, and present the whole stack as one coherent product.
It is not finished, and it is not meant to be. It is a stable baseline we can publish: accurate about what exists today, clear about what is still under development, and structured so that the API, SDK, and Entryway documentation can be added as those components ship.
What changed
Four sections. The site is organized into Guide, Client Integration, Reference, and Changes, each with its own sidebar. The root page is a short landing page that introduces the four.
Guide. A start-to-finish reading path that follows the same story as hypercerts.org one level deeper: why AT Protocol (including data ownership and portability), the shared language, activity claims, projects, evidence, evaluations, trust signals, funding, and where an application fits. Three diagrams illustrate trust building over time, account-owned records, and the records around one piece of work.
Reference: Lexicons. Every Hypercerts and Certified record type has a page with the same structure: what it is, how it is used, the schema, a validated example, usage conventions the schema can't express, and related records. The schema tables are generated at build time from the released
@hypercerts-org/lexiconpackage (1.4.1), so they cannot drift from the published schemas; bumping the package version updates every table.Reference: Services and tooling. An overview with an architecture diagram of the stack and the single list of running endpoints, plus one page per component: certified.app, Certified PDSs, Entryway, Certified Group Service, Relay and Jetstream, Indexer and Hypercerts API, Labelers, and Feed Service. The pages share one structure and reading level, each introduces the AT Protocol concept behind the service, and each has one code example. They are written for a project integrating with Hypercerts; operating your own instance is out of scope for now.
Reference: XRPC API and SDK. Placeholder pages that say what is coming and what to use until then. The Glossary (58 terms) and FAQ are rewritten to match.
Changes. Protocol release history and component versions, with changelogs imported from the component repositories and version badges read from their published releases.
Design. The site follows the Hypercerts design system through
@hypercerts-org/ui-react: tokens for colour, type, and radius, and library components where they fit. Dark mode is kept as a docs-site exception. The sidebar behaves like other documentation sites: category rows link to their page and expand.Documentation ownership. All pages are written in this repository. Component changelogs are the only imported content. The decision and the migration map are recorded in
docs/information-architecture.md.Tooling. The repository moves from npm to pnpm 12.
What was removed
Pages for things we no longer maintain or recommend, each with a redirect to the nearest current page or to the owning repository: the old Quickstart and Working with Evaluations, Scaffold, Hyperboards, the ePDS architecture page and tutorial, Hyperindex, and the Architecture overview. Hypercerts CLI and Hyperscan were already removed on
main.Coming next
Validation
pnpm test: 50 tests pass.pnpm run build: the static site builds.