From efc0557ff120c3bb2842d582d66c544a4c00597d Mon Sep 17 00:00:00 2001 From: daviddao Date: Fri, 20 Feb 2026 18:13:35 +0800 Subject: [PATCH 1/7] =?UTF-8?q?beads:=20plan=20docs-jss=20=E2=80=94=20READ?= =?UTF-8?q?ME.md=20and=20DEVELOPMENT.md=20for=20documentation=20project?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .beads/.gitignore | 1 + .beads/issues.jsonl | 3 +++ 2 files changed, 4 insertions(+) diff --git a/.beads/.gitignore b/.beads/.gitignore index 22f7963..0acd8c6 100644 --- a/.beads/.gitignore +++ b/.beads/.gitignore @@ -35,6 +35,7 @@ beads.right.meta.json # Sync state (local-only, per-machine) # These files are machine-specific and should not be shared across clones .sync.lock +.jsonl.lock sync_base.jsonl export-state/ diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index bd74eee..016b9d3 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -36,6 +36,9 @@ {"id":"docs-dfq.6","title":"Transition and hover state polish","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nAdd smooth transitions and refined hover states throughout the site, matching Stripe docs interaction patterns. All changes are CSS-only.\n\n### 1. Global transition timing\nAdd a CSS custom property for the standard transition in the `:root` design tokens section (around line 69, before the closing `}`):\n\n```css\n --transition-fast: 150ms ease;\n --transition-normal: 200ms cubic-bezier(0, 0.09, 0.4, 1);\n```\n\n### 2. Sidebar link transitions\nUpdate the existing `.sidebar-link` rule (line ~214-225). Add/modify the transition property:\n\nChange FROM:\n```css\n transition: background 0.1s ease;\n```\n\nChange TO:\n```css\n transition: background var(--transition-fast), color var(--transition-fast);\n```\n\n### 3. Sidebar active indicator\nAdd a left border indicator for the active sidebar link. Modify `.sidebar-link-active` (line ~233-237):\n\nChange FROM:\n```css\n.sidebar-link-active {\n font-weight: 600;\n color: var(--color-text-title);\n background: var(--hover-bg);\n}\n```\n\nChange TO:\n```css\n.sidebar-link-active {\n font-weight: 600;\n color: var(--color-link);\n background: var(--active-bg);\n border-left: 2px solid var(--color-link);\n padding-left: calc(var(--space-3) - 2px);\n}\n```\n\nAlso update `a.sidebar-link-active:hover` (line ~239-242):\n\nChange FROM:\n```css\na.sidebar-link-active:hover {\n background: var(--hover-bg);\n color: var(--color-text-title);\n}\n```\n\nChange TO:\n```css\na.sidebar-link-active:hover {\n background: var(--active-bg);\n color: var(--color-link);\n}\n```\n\n### 4. Pagination hover enhancement\nUpdate the `.pagination-link` transition (line ~354):\n\nChange FROM:\n```css\n transition: border-color 0.15s ease, box-shadow 0.15s ease;\n```\n\nChange TO:\n```css\n transition: border-color var(--transition-normal), box-shadow var(--transition-normal), transform var(--transition-normal);\n```\n\nAdd a subtle lift on hover. Update `.pagination-link:hover` (line ~357-361):\n\nChange FROM:\n```css\n.pagination-link:hover {\n border-color: var(--color-link);\n box-shadow: 0 1px 4px rgba(5, 112, 222, 0.08);\n text-decoration: none;\n}\n```\n\nChange TO:\n```css\n.pagination-link:hover {\n border-color: var(--color-link);\n box-shadow: 0 2px 8px rgba(5, 112, 222, 0.12);\n text-decoration: none;\n transform: translateY(-1px);\n}\n```\n\n### 5. TOC link transitions\nUpdate the `.toc-link` transition (line ~315):\n\nChange FROM:\n```css\n transition: color 0.15s ease, border-color 0.15s ease;\n```\n\nChange TO:\n```css\n transition: color var(--transition-fast), border-color var(--transition-fast);\n```\n\n### 6. Callout subtle left border animation\nAdd a transition to callout on hover:\n\n```css\n.callout {\n transition: box-shadow var(--transition-normal);\n}\n\n.callout:hover {\n box-shadow: 0 1px 4px rgba(0, 0, 0, 0.04);\n}\n```\n\nAdd these rules after the existing `.callout` rule (line ~533-537). Do NOT modify the existing `.callout` rule — add the transition property to a NEW `.callout` rule block that will merge via cascade, OR add the `transition` property directly into the existing `.callout` block.\n\n## Test\n```bash\ncd documentation \u0026\u0026 npm run build\n```\nMust exit 0. Additionally:\n```bash\ngrep \"transition-fast\" documentation/styles/globals.css \u0026\u0026 echo \"Tokens OK\"\ngrep \"transition-normal\" documentation/styles/globals.css \u0026\u0026 echo \"Tokens OK\"\ngrep \"translateY\" documentation/styles/globals.css \u0026\u0026 echo \"Pagination lift OK\"\ngrep \"border-left.*solid.*color-link\" documentation/styles/globals.css \u0026\u0026 echo \"Active indicator OK\"\n```\nAll four checks must pass.\n\n## Dont\n- Do not add page transition animations (route changes) — that requires JavaScript\n- Do not modify any JavaScript files\n- Do not change colors or font sizes\n- Do not add animation keyframes — only use CSS transitions\n- Do not modify the mobile responsive section","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T14:25:54.998064+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T20:03:35.256599+13:00","closed_at":"2026-02-14T20:03:35.256599+13:00","close_reason":"Implemented all transition and hover state polish: added transition timing variables, updated sidebar/TOC/pagination transitions, added active indicator with border-left, and callout hover effects","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-dfq.6","depends_on_id":"docs-dfq","type":"parent-child","created_at":"2026-02-14T14:25:54.998941+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-dfq.7","title":"Landing page card-style navigation links","description":"## Files\n- documentation/pages/index.md (modify)\n- documentation/components/CardLink.js (create)\n- documentation/markdoc/tags/card-link.markdoc.js (create)\n- documentation/pages/_app.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\nAdd card-style navigation links to the landing page, similar to Stripe docs landing pages that have categorized link cards with titles, descriptions, and hover effects.\n\n### 1. Create `documentation/components/CardLink.js`\n\nA card component for navigation links:\n\n```jsx\nimport Link from \"next/link\";\n\nexport function CardLink({ title, href, children }) {\n return (\n \u003cLink href={href} className=\"card-link\"\u003e\n \u003cspan className=\"card-link-title\"\u003e{title}\u003c/span\u003e\n {children \u0026\u0026 \u003cspan className=\"card-link-desc\"\u003e{children}\u003c/span\u003e}\n \u003cspan className=\"card-link-arrow\"\u003e→\u003c/span\u003e\n \u003c/Link\u003e\n );\n}\n```\n\n### 2. Create `documentation/markdoc/tags/card-link.markdoc.js`\n\nRegister the CardLink as a Markdoc tag:\n\n```js\nexport default {\n render: \"CardLink\",\n attributes: {\n title: { type: String, required: true },\n href: { type: String, required: true },\n },\n};\n```\n\n### 3. Modify `documentation/pages/_app.js`\n\nAdd import and register:\n\n```js\nimport { CardLink } from \"../components/CardLink\";\n```\n\nAdd to components object:\n```js\nconst components = {\n Callout,\n Columns,\n Column,\n Figure,\n Heading, // (if heading task is done, otherwise omit)\n CardLink,\n};\n```\n\n**IMPORTANT**: The components object may already contain `Heading` if task docs-dfq.2 was completed first. If `Heading` is already there, keep it. If not, do NOT add it — only add `CardLink`.\n\n### 4. Add CSS to `documentation/styles/globals.css`\n\nAdd a new section after the Figure component styles (around line ~597):\n\n```css\n/* ===== Component: CardLink ===== */\n.card-link {\n display: block;\n padding: var(--space-4) var(--space-5);\n border: 1px solid var(--color-border);\n border-radius: var(--radius-lg);\n text-decoration: none;\n transition: border-color 0.2s ease, box-shadow 0.2s ease, transform 0.2s ease;\n position: relative;\n margin-bottom: var(--space-3);\n}\n\n.card-link:hover {\n border-color: var(--color-link);\n box-shadow: 0 2px 8px rgba(5, 112, 222, 0.1);\n text-decoration: none;\n transform: translateY(-1px);\n}\n\n.card-link-title {\n display: block;\n font-size: 15px;\n font-weight: 600;\n color: var(--color-link);\n margin-bottom: var(--space-1);\n}\n\n.card-link-desc {\n display: block;\n font-size: 14px;\n color: var(--color-text-secondary);\n line-height: 1.5;\n}\n\n.card-link-arrow {\n position: absolute;\n right: var(--space-4);\n top: 50%;\n transform: translateY(-50%);\n color: var(--color-link);\n font-size: 16px;\n opacity: 0;\n transition: opacity 0.15s ease, transform 0.15s ease;\n}\n\n.card-link:hover .card-link-arrow {\n opacity: 1;\n transform: translateY(-50%) translateX(2px);\n}\n```\n\n### 5. Modify `documentation/pages/index.md`\n\nAdd a \"Quick Start\" section with card links after the existing content. Append to the end of the file:\n\n```markdown\n\n## Quick Start\n\n{% card-link title=\"Why We're Building Hypercerts\" href=\"/getting-started/why-were-building-hypercerts\" %}\nUnderstand the motivation behind the hypercerts protocol\n{% /card-link %}\n\n{% card-link title=\"Introduction to Impact Claims\" href=\"/getting-started/introduction-to-impact-claims\" %}\nLearn about impact claims and how they work\n{% /card-link %}\n\n{% card-link title=\"The Hypercerts Infrastructure\" href=\"/getting-started/the-hypercerts-infrastructure\" %}\nExplore the technical architecture\n{% /card-link %}\n\n{% card-link title=\"Introduction to Lexicons\" href=\"/lexicons/introduction-to-lexicons\" %}\nUnderstand the data schemas that power hypercerts\n{% /card-link %}\n```\n\n## Test\n```bash\ncd documentation \u0026\u0026 npm run build\n```\nMust exit 0. Additionally:\n```bash\ntest -f documentation/components/CardLink.js \u0026\u0026 echo \"Component OK\"\ntest -f documentation/markdoc/tags/card-link.markdoc.js \u0026\u0026 echo \"Tag OK\"\ngrep \"CardLink\" documentation/pages/_app.js \u0026\u0026 echo \"Registration OK\"\ngrep \"card-link\" documentation/styles/globals.css \u0026\u0026 echo \"CSS OK\"\ngrep \"card-link\" documentation/pages/index.md \u0026\u0026 echo \"Content OK\"\n```\nAll five checks must pass.\n\n## Dont\n- Do not modify existing content on the landing page — only append new content\n- Do not remove the existing columns/figures layout\n- Do not use any external icon libraries\n- Do not modify navigation.js\n- Do not add more than 4 card links","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T14:26:17.319286+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T20:07:08.03882+13:00","closed_at":"2026-02-14T20:07:08.03882+13:00","close_reason":"9969a9b Landing page card-style navigation links","labels":["scope:small"],"dependencies":[{"issue_id":"docs-dfq.7","depends_on_id":"docs-dfq","type":"parent-child","created_at":"2026-02-14T14:26:17.320306+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-dfq.8","title":"Integration: verify all refinements build and render correctly","description":"## Files\n- (no files to create/modify — verification only)\n\n## What to do\nAfter all other tasks in Epic 10 are complete, verify the full integration:\n\n1. Run `cd documentation \u0026\u0026 npm run build` — must exit 0 with no errors\n2. Verify all 17 pages are in the static export\n3. Spot-check that no CSS conflicts exist between the various refinements\n4. Verify the landing page renders with card links\n5. Verify breadcrumbs appear on non-home pages\n\n## Test\n```bash\ncd documentation \u0026\u0026 npm run build 2\u003e\u00261 | grep -c \"●\" | xargs test 17 -eq\n```\nMust show exactly 17 SSG pages.\n\n```bash\ncd documentation \u0026\u0026 npm run build\n```\nMust exit 0.\n\n## Dont\n- Do not modify any files\n- This is a verification-only task","status":"closed","priority":1,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T14:26:25.677169+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T20:10:10.53275+13:00","closed_at":"2026-02-14T20:10:10.53275+13:00","close_reason":"Closed","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq","type":"parent-child","created_at":"2026-02-14T14:26:25.678222+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.1","type":"blocks","created_at":"2026-02-14T14:26:31.650675+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.2","type":"blocks","created_at":"2026-02-14T14:26:31.749901+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.3","type":"blocks","created_at":"2026-02-14T14:26:31.849858+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.4","type":"blocks","created_at":"2026-02-14T14:26:31.950473+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.5","type":"blocks","created_at":"2026-02-14T14:26:32.047374+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.6","type":"blocks","created_at":"2026-02-14T14:26:32.141096+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.7","type":"blocks","created_at":"2026-02-14T14:26:32.236529+13:00","created_by":"Sharfy Adamantine"}]} +{"id":"docs-jss","title":"Epic: Add project-level README.md and DEVELOPMENT.md","description":"The documentation project lacks the standard project-level README.md and DEVELOPMENT.md files that our other repos (like hypercerts-scaffold-atproto) have. This epic adds both files following the same structure and style: comprehensive README with quick start, prerequisites, project structure, architecture; and DEVELOPMENT.md with local dev workflow, content authoring guide, Markdoc conventions, contributing, and troubleshooting. Success: a new contributor can clone the repo, run the docs site locally, and add a new page — all by reading README + DEVELOPMENT only.","status":"open","priority":2,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-20T18:12:19.646036+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:12:19.646036+08:00","labels":["scope:medium"]} +{"id":"docs-jss.1","title":"Create README.md at project root","description":"## Files\n- README.md (create)\n\n## What to do\nCreate a comprehensive README.md at the repo root following the structure and style of hypercerts-scaffold-atproto/README.md. The file must include these sections in order:\n\n1. **Title \u0026 description** — \"Hypercerts Documentation\" heading. One paragraph: this is the official documentation site for the Hypercerts protocol, built with Next.js and Markdoc, deployed on Vercel.\n\n2. **Prerequisites** — Node.js 20+, npm (not pnpm — the project uses npm per vercel.json and package-lock.json).\n\n3. **Quick Start** — Clone, cd documentation/documentation, npm install, npm run dev. Note the nested directory structure (the actual Next.js app lives in documentation/documentation/).\n\n4. **Project Structure** — ASCII tree showing:\n```\n├── documentation/ # Next.js documentation site\n│ ├── components/ # React components (Layout, Sidebar, CodeBlock, etc.)\n│ ├── lib/ # Navigation config and helpers\n│ ├── markdoc/ # Markdoc tag and node definitions\n│ │ ├── nodes/ # Custom node renderers (fence, heading)\n│ │ └── tags/ # Custom tags (callout, card-link, columns, figure)\n│ ├── pages/ # Documentation content (.md files)\n│ │ ├── architecture/\n│ │ ├── core-concepts/\n│ │ ├── ecosystem/\n│ │ ├── getting-started/\n│ │ ├── lexicons/\n│ │ ├── reference/\n│ │ └── tools/\n│ ├── public/ # Static assets\n│ └── styles/ # CSS\n├── heartbeads-agents/ # (reserved)\n├── AGENTS.md # Agent workflow instructions\n└── .beads/ # Issue tracking\n```\n\n5. **Content Sections** — Table listing the 7 doc sections (Get Started, Core Concepts, Tools, Architecture, Reference/Lexicons, Ecosystem \u0026 Vision) with one-line descriptions, matching the style of the scaffold README tables.\n\n6. **Deployment** — State that the site is deployed on Vercel. The build command is `next build --webpack`, install command is `npm install`. Static export via `output: \"export\"` in next.config.js.\n\n7. **Learn More** — Links to: Hypercerts website (https://hypercerts.org), ATProto docs (https://atproto.com/docs), Markdoc docs (https://markdoc.dev), Next.js docs (https://nextjs.org/docs), DEVELOPMENT.md for contributor guide.\n\n## Don't\n- Do NOT mention pnpm — this project uses npm\n- Do NOT include any authentication, OAuth, or SDK content (this is a docs site, not an application)\n- Do NOT copy scaffold-specific sections (environment variables, Redis, JWK keys, etc.)\n- Do NOT add a License section (there is none currently)\n- Keep it under 150 lines","acceptance_criteria":"1. README.md exists at /Users/david/Projects/gainforest/documentation/README.md\n2. Contains all 7 sections listed in spec: title, prerequisites, quick start, project structure, content sections, deployment, learn more\n3. Quick Start instructions work: cd documentation/documentation \u0026\u0026 npm install \u0026\u0026 npm run dev starts the dev server\n4. References npm (not pnpm) throughout\n5. Project structure ASCII tree accurately reflects actual directory layout\n6. No scaffold-specific content (no Redis, OAuth, JWK, SDK references)\n7. File is under 150 lines\n8. All links in Learn More section are valid URLs","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-20T18:12:47.807873+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:12:47.807873+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-jss.1","depends_on_id":"docs-jss","type":"parent-child","created_at":"2026-02-20T18:12:47.809207+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-jss.2","title":"Create DEVELOPMENT.md at project root","description":"## Files\n- DEVELOPMENT.md (create)\n\n## What to do\nCreate a comprehensive DEVELOPMENT.md at the repo root following the structure and style of hypercerts-scaffold-atproto/DEVELOPMENT.md. The file must include these sections in order:\n\n1. **Local Development Workflow** heading, then:\n - **Prerequisites** — Node.js 20+, npm, Git\n - **First-time Setup** — Step-by-step: clone, cd documentation/documentation, npm install, npm run dev, open http://localhost:3000. Note the nested directory structure.\n - **Daily Development** — Just `npm run dev` in the documentation/documentation/ directory.\n - **Build for production** — `npm run build` (produces static export in `out/` directory).\n\n2. **Adding Documentation Pages** — This is the content authoring guide:\n - Explain that pages are Markdoc files (.md) in `documentation/pages/`\n - File location determines URL path (e.g., `pages/getting-started/quickstart.md` → `/getting-started/quickstart`)\n - Every page needs YAML frontmatter with `title` (required) and `description` (optional)\n - Show a template:\n ```markdown\n ---\n title: Page Title\n description: One-line description.\n ---\n\n # Page Title\n\n Content goes here.\n ```\n - After creating a page, add it to the navigation in `documentation/lib/navigation.js`\n - Explain navigation.js structure briefly: top-level items have `title` + `path`, sections have `section` + `children` array, nesting is supported\n\n3. **Markdoc Custom Tags** — List available custom tags with usage examples:\n - `{% callout type=\"note|warning|caution\" %}...{% /callout %}` — callout boxes\n - `{% card-link title=\"...\" href=\"...\" %}...{% /card-link %}` — linked cards\n - `{% columns %}{% column %}...{% /column %}{% column %}...{% /column %}{% /columns %}` — multi-column layout\n - `{% figure src=\"...\" alt=\"...\" caption=\"...\" /%}` — images with captions\n\n4. **Project Architecture** — Brief explanation:\n - Next.js with Markdoc plugin for static site generation\n - `output: \"export\"` produces fully static HTML (no server needed)\n - `pageExtensions: [\"md\", \"mdoc\", \"js\", \"jsx\", \"ts\", \"tsx\"]` — Markdoc files are treated as pages\n - Components in `components/` provide the layout shell (Layout.js), sidebar navigation (Sidebar.js), syntax highlighting (CodeBlock.js), breadcrumbs, etc.\n\n5. **Troubleshooting** — Common issues:\n - \"Module not found\" → run `npm install`\n - Page not appearing in sidebar → check navigation.js\n - Markdoc syntax errors → check tag matching ({% tag %}...{% /tag %})\n - Build fails → ensure Node.js 20+\n\n6. **Contributing** — Follow the same structure as the scaffold:\n - Fork, branch, make changes, test with `npm run build`, open PR\n - Content PRs: new/updated .md files + navigation.js update\n - Component PRs: test visually with `npm run dev`\n\n## Don't\n- Do NOT mention pnpm — this project uses npm\n- Do NOT include SDK, OAuth, Redis, or application-specific content\n- Do NOT copy the \"Updating the Vendor SDK Package\" section from the scaffold\n- Do NOT invent Markdoc tags that do not exist in the markdoc/tags/ directory — only document callout, card-link, columns/column, and figure\n- Keep it under 250 lines","acceptance_criteria":"1. DEVELOPMENT.md exists at /Users/david/Projects/gainforest/documentation/DEVELOPMENT.md\n2. Contains all 6 sections: local dev workflow, adding pages, markdoc custom tags, project architecture, troubleshooting, contributing\n3. First-time setup instructions work: cd documentation/documentation \u0026\u0026 npm install \u0026\u0026 npm run dev\n4. Markdoc tags documented match exactly what exists in documentation/markdoc/tags/: callout, card-link, columns/column, figure (no extras, no missing)\n5. Navigation.js path is correctly referenced as documentation/lib/navigation.js\n6. References npm (not pnpm) throughout\n7. Frontmatter template shows title (required) and description (optional)\n8. File is under 250 lines\n9. No SDK, OAuth, Redis, or application-specific content","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-20T18:13:19.095143+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:13:19.095143+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-jss.2","depends_on_id":"docs-jss","type":"parent-child","created_at":"2026-02-20T18:13:19.096301+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-l7r","title":"Epic: Ecosystem, Community \u0026 Reference Materials","status":"closed","priority":2,"issue_type":"epic","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T20:47:56.489643+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-15T01:08:20.711096+13:00","closed_at":"2026-02-15T01:08:20.711096+13:00","close_reason":"All children complete: l7r.1 (glossary + FAQ), l7r.2 (building on hypercerts)"} {"id":"docs-l7r.1","title":"Write 'Glossary' and 'FAQ' reference pages","description":"## Context\n\nDocumentation site for the Hypercerts Protocol, built with Next.js 16 + Markdoc. Site lives in `documentation/`. Pages are `.md` files in `documentation/pages/`. Nav in `documentation/lib/navigation.js`. Markdoc tags: `{% callout %}`, `{% columns %}`, `{% column %}`, `{% figure %}`, `{% card-link %}`.\n\nStripe has inline glossary definitions throughout and extensive support articles. Hypercerts uses many domain-specific terms (DID, PDS, lexicon, work scope, strong reference, etc.) but never defines them in one place. This task creates two pages.\n\n## Files\n- documentation/pages/reference/glossary.md (create)\n- documentation/pages/reference/faq.md (create)\n- documentation/lib/navigation.js (modify — add entries under Reference section)\n\n## What to do\n\n### 1. Create the Glossary page\n\nCreate `documentation/pages/reference/glossary.md` (80–120 lines of Markdoc):\n\n**Frontmatter:**\n```\n---\ntitle: Glossary\ndescription: Key terms and definitions used in the Hypercerts Protocol.\n---\n```\n\nDefine these terms (alphabetical order), each as `#### Term` followed by 1-3 sentence definition:\n\n- **Activity Claim** — The central record in the hypercerts data model. Describes who did what, when, and where. Lexicon: `org.hypercerts.claim.activity`.\n- **AT Protocol (ATProto)** — A decentralized social data protocol. The data layer for Hypercerts. Provides portable identity, shared schemas, and federation.\n- **CID** — Content Identifier. A cryptographic hash of a record's content, used in strong references to ensure tamper-evidence.\n- **Collection** — A group of hypercerts with a shared property, where each claim has a weight. Lexicon: `org.hypercerts.claim.collection`.\n- **Contribution** — A record describing a specific contributor's role in an activity claim. Lexicon: `org.hypercerts.claim.contribution`.\n- **DID (Decentralized Identifier)** — A persistent, cryptographically verifiable identifier for a person or organization. Format: `did:plc:...` or `did:web:...`.\n- **Evaluation** — A third-party assessment of a hypercert or other claim. Created on the evaluator's own PDS. Lexicon: `org.hypercerts.claim.evaluation`.\n- **Evidence** — A piece of supporting documentation attached to a hypercert. Can be a URI or uploaded blob. Lexicon: `org.hypercerts.claim.evidence`.\n- **Hypercert** — A structured digital record of a contribution: who did what, when, where, and with what evidence. The core primitive of the protocol.\n- **Indexer (App View)** — A service that reads from relays and builds queryable views of hypercert data across many PDS instances.\n- **Lexicon** — An ATProto schema definition that specifies the structure of a record type. Like a form template with required and optional fields.\n- **Measurement** — A quantitative observation attached to a claim. Lexicon: `org.hypercerts.claim.measurement`.\n- **PDS (Personal Data Server)** — A server that stores a user's ATProto data. Users can self-host or use a provider.\n- **Relay** — An ATProto service that aggregates data from many PDS instances and streams it to indexers.\n- **Rights** — A record describing what rights a holder has to a hypercert (display, transfer, etc.). Lexicon: `org.hypercerts.claim.rights`.\n- **SDS (Shared Data Server)** — Like a PDS but for organizations. Multiple users can write to the same repository.\n- **Strong Reference** — An ATProto reference that includes both the AT URI and CID of the target record, ensuring the reference is tamper-evident.\n- **Work Scope** — The \"what\" dimension of a hypercert, defined using logical operators (allOf, anyOf, noneOf) to precisely bound the work being claimed.\n- **XRPC** — The RPC protocol used by ATProto for client-server communication.\n\n### 2. Create the FAQ page\n\nCreate `documentation/pages/reference/faq.md` (80–120 lines of Markdoc):\n\n**Frontmatter:**\n```\n---\ntitle: Frequently Asked Questions\ndescription: Common questions about the Hypercerts Protocol.\n---\n```\n\nAnswer these questions (use `##` for each question, 2-4 sentences per answer):\n\n1. **What is a hypercert?** — A structured digital record of a contribution. It captures who did what, when, where, and with what evidence.\n2. **How is this different from the previous (EVM-based) Hypercerts?** — The new protocol is built on AT Protocol instead of purely on-chain. This gives data portability, richer schemas, and lower costs, while still using blockchain for ownership and funding.\n3. **Do I need a blockchain wallet?** — Not to create or evaluate hypercerts. You need an ATProto account (DID). A wallet is only needed if you want to tokenize or fund hypercerts on-chain.\n4. **Is my data public?** — Yes. All ATProto records are public by default. Do not store sensitive personal information in hypercert records.\n5. **Can I delete a hypercert?** — You can delete records from your PDS. However, cached copies may persist in indexers and relays.\n6. **Who can evaluate my hypercert?** — Anyone with an ATProto account. Evaluations are separate records on the evaluator's PDS, linked via strong references.\n7. **How do I fund a hypercert?** — Funding happens on-chain through tokenized ownership. The specific mechanisms depend on the platform you use.\n8. **Can I use my Bluesky account?** — Yes. Bluesky accounts are ATProto accounts. Your existing DID works with Hypercerts.\n9. **What chains are supported?** — The protocol is chain-agnostic for the ownership layer. Specific chain support depends on the implementation.\n10. **How do I get help?** — Link to GitHub repository, community channels (use placeholder URLs with a callout).\n\n### 3. Add to navigation\n\nAdd under the Reference section in `documentation/lib/navigation.js`:\n```javascript\n{ title: 'Glossary', path: '/reference/glossary' },\n{ title: 'FAQ', path: '/reference/faq' },\n```\nIf the Reference section does not yet exist, create it after Architecture.\n\n## Test\n```\ncd documentation \u0026\u0026 npx next build 2\u003e\u00261 | tail -5\n```\nMust exit 0.\n\n## Dont\n- Do NOT add images or new components.\n- Do NOT modify existing pages other than navigation.js.\n- Do NOT use HTML tags.\n- Do NOT invent features or capabilities not described in the existing documentation.","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T20:54:01.702733+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-15T01:06:09.77014+13:00","closed_at":"2026-02-15T01:06:09.77014+13:00","close_reason":"Created Glossary and FAQ reference pages with proper navigation","dependencies":[{"issue_id":"docs-l7r.1","depends_on_id":"docs-l7r","type":"parent-child","created_at":"2026-02-14T20:54:01.704171+13:00","created_by":"Sharfy Adamantine"}],"comments":[{"id":10,"issue_id":"docs-l7r.1","author":"Sharfy Adamantine","text":"NAV UPDATE: Add under 'Reference' section. Full nav order: Get Started → Core Concepts → Architecture → Lexicons → Tutorials → Reference.","created_at":"2026-02-14T11:25:02Z"},{"id":11,"issue_id":"docs-l7r.1","author":"Sharfy Adamantine","text":"DESIGN LANGUAGE: Follow Stripe docs (docs.stripe.com) patterns — concise definitions, scannable. No preamble, no link dumps. BUILD COMMAND FIX: Use 'cd documentation \u0026\u0026 npx next build --webpack 2\u003e\u00261 | tail -5' (must include --webpack flag). NAV PLACEMENT: Add under Reference section AFTER 'Tutorials'.","created_at":"2026-02-14T11:58:22Z"}]} {"id":"docs-l7r.2","title":"Write 'Building on Hypercerts' ecosystem guide page","description":"## Context\n\nDocumentation site for the Hypercerts Protocol, built with Next.js 16 + Markdoc. Site lives in `documentation/`. Pages are `.md` files in `documentation/pages/`. Nav in `documentation/lib/navigation.js`. Markdoc tags: `{% callout %}`, `{% columns %}`, `{% column %}`, `{% figure %}`, `{% card-link %}`.\n\nStripe's equivalent: \"Stripe Apps\" and \"Partners\" pages — guides for third parties who want to build on the platform. The hypercerts \"Why\" page mentions that the protocol is designed for many platforms to build on, but there is no guide for platform builders.\n\n## Files\n- documentation/pages/reference/building-on-hypercerts.md (create)\n- documentation/lib/navigation.js (modify — add entry under Reference section)\n\n## What to do\n\n### 1. Create the page\n\nCreate `documentation/pages/reference/building-on-hypercerts.md` (100–150 lines of Markdoc):\n\n**Frontmatter:**\n```\n---\ntitle: Building on Hypercerts\ndescription: A guide for platforms and tools that want to integrate the Hypercerts Protocol.\n---\n```\n\n**Sections:**\n\n1. **Who This Is For** — Platform builders, funding tool developers, evaluation services, dashboards, and anyone building applications that read or write hypercert data.\n\n2. **What You Can Build** — Categories of applications:\n - **Funding Platforms**: Crowdfunding, retroactive funding, milestone-based payouts using tokenized hypercerts\n - **Evaluation Tools**: Services that help domain experts create structured evaluations\n - **Dashboards \u0026 Explorers**: Interfaces that aggregate and display hypercerts across the ecosystem\n - **Impact Portfolios**: Tools that let funders track their portfolio of funded contributions\n - **Automated Agents**: AI systems that create measurements, flag inconsistencies, or assist evaluators\n\n3. **Integration Patterns** — How to integrate:\n - **Read-only**: Query an indexer to display hypercerts (simplest). No PDS needed.\n - **Write via user PDS**: Your app authenticates users via OAuth and writes records to their PDS on their behalf.\n - **Write via platform SDS**: Your platform runs its own Shared Data Server and creates records under its own DID.\n - For each pattern, provide 3-4 sentences explaining when to use it and a brief code sketch.\n\n4. **Running an Indexer** — Brief overview:\n - Subscribe to the relay firehose for hypercert lexicon records\n - Build a queryable database (PostgreSQL, etc.)\n - Expose an API for your application\n - Note: link to ATProto docs for relay subscription details\n\n5. **Interoperability Principles** — What makes the ecosystem work:\n - Use standard lexicons — do not create custom record types for data that fits existing schemas\n - Use strong references — always include CID for tamper-evidence\n - Respect data ownership — records belong to the DID that created them\n - Build for federation — do not assume all data lives on one PDS\n\n6. **Contributing to the Protocol** — How to propose changes:\n - Lexicon evolution process (propose → discuss → implement)\n - Link to GitHub repository (placeholder URL with callout)\n - How to contribute to the SDK\n\n### 2. Add to navigation\n\nAdd under the Reference section in `documentation/lib/navigation.js`:\n```javascript\n{ title: 'Building on Hypercerts', path: '/reference/building-on-hypercerts' },\n```\n\n## Test\n```\ncd documentation \u0026\u0026 npx next build 2\u003e\u00261 | tail -5\n```\nMust exit 0.\n\n## Dont\n- Do NOT add images or new components.\n- Do NOT modify existing pages other than navigation.js.\n- Do NOT use HTML tags.\n- Do NOT invent specific indexer APIs or relay endpoints.","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T20:54:24.391792+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-15T01:05:12.774851+13:00","closed_at":"2026-02-15T01:05:12.774851+13:00","close_reason":"Created Building on Hypercerts guide page with integration patterns, interoperability principles, and contribution guidelines. Build passes.","dependencies":[{"issue_id":"docs-l7r.2","depends_on_id":"docs-l7r","type":"parent-child","created_at":"2026-02-14T20:54:24.393036+13:00","created_by":"Sharfy Adamantine"}],"comments":[{"id":12,"issue_id":"docs-l7r.2","author":"Sharfy Adamantine","text":"NAV UPDATE: Add under 'Reference' section. Full nav order: Get Started → Core Concepts → Architecture → Lexicons → Tutorials → Reference.","created_at":"2026-02-14T11:25:03Z"},{"id":13,"issue_id":"docs-l7r.2","author":"Sharfy Adamantine","text":"DESIGN LANGUAGE: Follow Stripe docs (docs.stripe.com) patterns — one-sentence opener, capability bullet list, code-first, short paragraphs, no preamble, no link dumps. BUILD COMMAND FIX: Use 'cd documentation \u0026\u0026 npx next build --webpack 2\u003e\u00261 | tail -5' (must include --webpack flag). NAV PLACEMENT: Add under Reference section AFTER 'Tutorials'.","created_at":"2026-02-14T11:58:23Z"}]} From 069a19c7d83997cfa63e06a56bfd1429fadcdbcf Mon Sep 17 00:00:00 2001 From: daviddao Date: Fri, 20 Feb 2026 18:21:24 +0800 Subject: [PATCH 2/7] =?UTF-8?q?beads:=20plan=20docs-1ho=20=E2=80=94=20adop?= =?UTF-8?q?t=20scaffold=20visual=20design=20language=20(fonts,=20colors,?= =?UTF-8?q?=20radii,=20typography)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .beads/issues.jsonl | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 016b9d3..1e9fa13 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -3,6 +3,12 @@ {"id":"docs-150.2","title":"Sidebar: move chevron to left side, make inline, reduce size to 12px","description":"## Files\n- documentation/components/Sidebar.js (modify)\n\n## What to do\nStripe places the expand/collapse chevron to the LEFT of the link text, inline within the link element. Ours is a separate button on the right side. Also reduce chevron from 16x16 to 12x12 and change nesting indent from 16px increments to 12px.\n\nReplace the NavItem component (lines 18-89) with this version that puts the chevron inline before the text:\n\n```js\nfunction NavItem({ item, currentPath, depth = 0 }) {\n const hasChildren = item.children \u0026\u0026 item.children.length \u003e 0;\n const active = item.path \u0026\u0026 isActive(item.path, currentPath);\n const childActive = hasChildren \u0026\u0026 isChildActive(item, currentPath);\n const [expanded, setExpanded] = useState(childActive || active);\n\n useEffect(() =\u003e {\n if (childActive || active) {\n setExpanded(true);\n }\n }, [childActive, active]);\n\n const handleToggle = (e) =\u003e {\n if (hasChildren) {\n e.preventDefault();\n setExpanded(!expanded);\n }\n };\n\n const paddingLeft = `${12 + depth * 12}px`;\n\n const chevron = hasChildren ? (\n \u003csvg\n className=\"sidebar-chevron\"\n width=\"12\"\n height=\"12\"\n viewBox=\"0 0 16 16\"\n fill=\"none\"\n style={{\n transform: expanded ? \"rotate(90deg)\" : \"rotate(0deg)\",\n transition: \"transform 0.15s ease\",\n }}\n \u003e\n \u003cpath\n d=\"M6 4l4 4-4 4\"\n stroke=\"currentColor\"\n strokeWidth=\"1.5\"\n strokeLinecap=\"round\"\n strokeLinejoin=\"round\"\n /\u003e\n \u003c/svg\u003e\n ) : null;\n\n return (\n \u003cli className=\"sidebar-nav-item\"\u003e\n {item.path ? (\n \u003cLink\n href={item.path}\n className={`sidebar-link${active ? \" sidebar-link-active\" : \"\"}${\n childActive ? \" sidebar-link-parent-active\" : \"\"\n }`}\n style={{ paddingLeft }}\n onClick={hasChildren \u0026\u0026 !item.path ? handleToggle : undefined}\n \u003e\n {chevron}\n {item.title}\n \u003c/Link\u003e\n ) : (\n \u003cspan\n className={`sidebar-link sidebar-link-toggle${\n childActive ? \" sidebar-link-parent-active\" : \"\"\n }`}\n style={{ paddingLeft }}\n onClick={handleToggle}\n \u003e\n {chevron}\n {item.title}\n \u003c/span\u003e\n )}\n {hasChildren \u0026\u0026 expanded \u0026\u0026 (\n \u003cul className=\"sidebar-nav-children\"\u003e\n {item.children.map((child) =\u003e (\n \u003cNavItem\n key={child.path || child.title}\n item={child}\n currentPath={currentPath}\n depth={depth + 1}\n /\u003e\n ))}\n \u003c/ul\u003e\n )}\n \u003c/li\u003e\n );\n}\n```\n\nKey changes:\n1. Removed the separate `.sidebar-nav-link-row` div wrapper\n2. Removed the separate `.sidebar-expand-btn` button\n3. Chevron SVG is now inline BEFORE the text inside the link/span\n4. Chevron is 12x12 (was 16x16)\n5. Indent is `12 + depth * 12` (was `16 + depth * 16`)\n6. Non-link parents with children get class `sidebar-link-toggle` and onClick to toggle\n7. Added `sidebar-chevron` class to the SVG for CSS styling\n\n## Test\n```bash\ncd documentation \u0026\u0026 node -e \"\nconst fs = require(\\\"fs\\\");\nconst src = fs.readFileSync(\\\"components/Sidebar.js\\\", \\\"utf8\\\");\nconst hasInlineChevron = src.includes(\\\"sidebar-chevron\\\");\nconst noExpandBtn = !src.includes(\\\"sidebar-expand-btn\\\");\nconst noLinkRow = !src.includes(\\\"sidebar-nav-link-row\\\");\nconst has12px = src.includes(\\\"12 + depth * 12\\\");\nconst has12x12 = src.includes(\\\"width=\\\\\\\"12\\\\\\\"\\\") \u0026\u0026 src.includes(\\\"height=\\\\\\\"12\\\\\\\"\\\");\nif (!hasInlineChevron) { console.error(\\\"FAIL: no sidebar-chevron class\\\"); process.exit(1); }\nif (!noExpandBtn) { console.error(\\\"FAIL: still has sidebar-expand-btn\\\"); process.exit(1); }\nif (!noLinkRow) { console.error(\\\"FAIL: still has sidebar-nav-link-row\\\"); process.exit(1); }\nif (!has12px) { console.error(\\\"FAIL: indent not 12px increments\\\"); process.exit(1); }\nif (!has12x12) { console.error(\\\"FAIL: chevron not 12x12\\\"); process.exit(1); }\nconsole.log(\\\"PASS\\\");\n\"\n```\n\n## Dont\n- Do not change NavSection or the Sidebar export function\n- Do not change the collapse button (sidebar-collapse-btn)\n- Do not touch globals.css (CSS handled separately)\n- Do not change the navigation data import","status":"closed","priority":1,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:24:05.829993+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:27:45.00586+13:00","closed_at":"2026-02-14T22:27:45.00586+13:00","close_reason":"d3a98d1 - Sidebar chevron moved to left side, inline, 12px (implemented alongside docs-150.1)","dependencies":[{"issue_id":"docs-150.2","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:24:05.831325+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-150.3","title":"Breadcrumbs: lighter separator color, wider spacing","description":"## Files\n- documentation/components/Breadcrumbs.js (modify)\n\n## What to do\nUpdate the breadcrumb separator color and spacing to match Stripe. Currently the separator uses a dark gray; Stripe uses a lighter gray with more spacing.\n\nRead the current Breadcrumbs.js file first. Find the separator span element and update:\n1. The separator character should remain \"/\" \n2. No changes needed in the JS — the color/spacing changes are CSS-only\n\nActually, this task requires NO JS changes. The separator styling is in globals.css. Cancel this task — the CSS mega-task will handle it.\n\n## Test\nN/A — this task should be cancelled\n\n## Dont\nN/A","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:24:15.360221+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:24:21.845024+13:00","closed_at":"2026-02-14T22:24:21.845027+13:00","dependencies":[{"issue_id":"docs-150.3","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:24:15.361244+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-150.4","title":"Mega CSS: all 25 Stripe parity fixes in globals.css","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nApply ALL of the following CSS changes to globals.css. Each change is numbered and references the current line. Read the file first to confirm line numbers, then apply all changes.\n\n### Design Token Changes (in :root block, lines 72-136)\n\n1. **Unify heading colors** — Change line 87 `--color-text-heading: #353a44` to `--color-text-heading: #1a1b25` and line 88 `--color-text-title: #21252c` to `--color-text-title: #1a1b25`\n\n2. **Content max-width** — Change line 110 `--content-max-width: 800px` to `--content-max-width: 880px`\n\n3. **TOC width** — Change line 109 `--toc-width: 200px` to `--toc-width: 250px`\n\n### Add responsive sidebar width (after the :root closing brace, ~line 136)\n\n4. **Sidebar responsive** — Add after the `:root` block:\n```css\n@media (min-width: 1400px) {\n :root {\n --sidebar-width: 280px;\n }\n}\n```\n\n### Header Changes (lines 175-221)\n\n5. **Header background** — Change line 181 from `background: rgba(255, 255, 255, 0.95)` to `background: #f6f8fa`. Remove lines 182-183 (`backdrop-filter` and `-webkit-backdrop-filter`).\n\n6. **Logo font-size** — Change line 196 `font-size: 15px` to `font-size: 16px`\n\n### Breadcrumb Changes (lines 223-268)\n\n7. **Breadcrumb font-size** — Change line 235 `font-size: 13px` to `font-size: 14px`\n\n8. **Breadcrumb separator** — Change line 245 `margin: 0 6px` to `margin: 0 8px`. Change line 246 `color: var(--color-text-secondary)` to `color: #a3acba`\n\n### Sidebar Changes (lines 275-439)\n\n9. **Sidebar content padding** — Change line 304 `padding: var(--space-6) 0` to `padding: var(--space-3) 0`\n\n10. **Sidebar section spacing** — Change line 350 `margin-top: var(--space-5)` to `margin-top: var(--space-4)` and line 351 `padding-top: var(--space-5)` to `padding-top: var(--space-4)`\n\n11. **Sidebar section header** — Change the `.sidebar-section-header` rule (lines 362-369):\n```css\n.sidebar-section-header {\n font-size: 12px;\n font-weight: 600;\n text-transform: uppercase;\n letter-spacing: 0.05em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-4);\n margin-bottom: var(--space-2);\n}\n```\n\n12. **Sidebar link density** — In `.sidebar-link` (lines 384-395), change `padding: 6px var(--space-3)` to `padding: 4px var(--space-2)` and change `border-radius: var(--radius-md)` to `border-radius: var(--radius-sm)`\n\n13. **Remove old sidebar-nav-link-row and sidebar-expand-btn rules** — Delete the `.sidebar-nav-link-row` rule (lines 379-382) and the `.sidebar-expand-btn` rules (lines 420-435). These are no longer used since the chevron is now inline.\n\n14. **Add sidebar-chevron styling** — Add after the `.sidebar-link` rules:\n```css\n.sidebar-chevron {\n flex-shrink: 0;\n margin-right: 4px;\n color: var(--color-text-secondary);\n}\n```\n\n15. **Add sidebar-link-toggle** — Add:\n```css\n.sidebar-link-toggle {\n cursor: pointer;\n}\n```\n\n16. **Sidebar link needs flex for inline chevron** — Add `display: flex; align-items: center;` to `.sidebar-link` (it currently has `display: block`). Change `display: block` to `display: flex` and add `align-items: center;`\n\n17. **Sidebar active link** — Change `.sidebar-link-active` (lines 403-407):\n```css\n.sidebar-link-active {\n color: var(--color-link);\n font-weight: 500;\n background: none;\n border-left: 2px solid var(--color-link);\n margin-left: -2px;\n}\n```\n\n18. **Sidebar parent-of-active** — Change `.sidebar-link-parent-active` (lines 415-418):\n```css\n.sidebar-link-parent-active {\n font-weight: 500;\n color: var(--color-text-primary);\n}\n```\n\n### Content Area Changes (lines 441-451)\n\n19. **Content padding** — Change line 446 `padding: var(--space-10) var(--space-12)` to `padding: var(--space-8) var(--space-10)` (32px top, 40px sides)\n\n### TOC Changes (lines 453-502)\n\n20. **TOC link font-size** — Change line 484 `font-size: 13px` to `font-size: 14px`\n\n21. **TOC link spacing** — Change line 483 `padding: var(--space-1) 0` to `padding: var(--space-2) 0`\n\n22. **TOC title margin** — Change line 474 `margin-bottom: var(--space-2)` to `margin-bottom: var(--space-4)`\n\n23. **Add TOC H3 indentation** — Add after the `.toc-link-active` rule:\n```css\n.toc-link-h3 {\n padding-left: 22px;\n font-size: 13px;\n}\n```\n\n24. **TOC responsive breakpoint** — Change line 878 `@media (max-width: 1100px)` to `@media (max-width: 1200px)`\n\n### Typography Changes (lines 556-705)\n\n25. **H1** — Remove `letter-spacing: -0.02em` from `.layout-content h1` (line 564)\n\n26. **H2** — Change `.layout-content h2` (lines 567-574): `font-size: 24px`, `line-height: 32px` (was 20px / 28px)\n\n27. **H3** — Change `.layout-content h3` (lines 576-583): `font-size: 16px`, `font-weight: 700` (was 18px / 600)\n\n28. **Paragraph spacing** — Change line 633 `margin-bottom: var(--space-4)` to `margin-bottom: var(--space-3)` (12px)\n\n29. **Bold text** — Change line 598 `font-weight: 600` to `font-weight: 700`\n\n30. **Inline code border** — In the inline code rule (lines 689-696), add `border: 1px solid var(--color-border)` and change `padding: 2px 6px` to `padding: 1px 4px`\n\n31. **Code blocks dark theme** — Change `.layout-content pre` (lines 671-681):\n```css\n.layout-content pre {\n background: #0a2540;\n padding: var(--space-4);\n border-radius: var(--radius-sm);\n overflow-x: auto;\n margin-bottom: var(--space-4);\n font-family: var(--font-mono);\n font-size: 13px;\n line-height: 19px;\n color: #f5fbff;\n}\n```\n\n32. **Code block scrollbar** — Update the code block scrollbar thumb colors (lines 47-54) to work on dark background: change `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)` and `rgba(0, 0, 0, 0.2)` to `rgba(255, 255, 255, 0.25)`. Also update the Firefox scrollbar-color on line 70 from `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)`.\n\n33. **Blockquote** — Change `.layout-content blockquote` (lines 733-738): `border-left: 1px solid #c0c8d2` (was 4px solid var(--color-border)), `padding: 5px 0 5px 10px` (was 0 16px), add `font-size: 14px; line-height: 20px`\n\n34. **Table headers** — In `.layout-content th` (lines 714-720), add `text-transform: uppercase; font-size: 13px; letter-spacing: 0.03em`\n\n35. **Scrollbar gutter** — Add `scrollbar-gutter: stable;` to `.sidebar-content` (around line 303)\n\n### Link styling\n\n36. **Content links** — Change `.layout-content a` (lines 657-662): remove `border-bottom: 1px solid transparent` and add `text-decoration: underline; text-underline-offset: 2px; text-decoration-color: rgba(5, 112, 222, 0.4)`. Change `.layout-content a:hover` (lines 664-668): remove `border-bottom-color` line, change to `text-decoration-color: var(--color-link-hover)`\n\n## Test\n```bash\ncd documentation \u0026\u0026 node -e \"\nconst fs = require(\\\"fs\\\");\nconst css = fs.readFileSync(\\\"styles/globals.css\\\", \\\"utf8\\\");\nconst checks = [\n [css.includes(\\\"--color-text-heading: #1a1b25\\\"), \\\"heading color unified\\\"],\n [css.includes(\\\"--color-text-title: #1a1b25\\\"), \\\"title color unified\\\"],\n [css.includes(\\\"--content-max-width: 880px\\\"), \\\"content max-width 880\\\"],\n [css.includes(\\\"--toc-width: 250px\\\"), \\\"toc width 250\\\"],\n [css.includes(\\\"min-width: 1400px\\\"), \\\"responsive sidebar\\\"],\n [css.includes(\\\"background: #f6f8fa\\\") || css.includes(\\\"background:#f6f8fa\\\"), \\\"header solid bg\\\"],\n [css.includes(\\\"background: #0a2540\\\"), \\\"dark code blocks\\\"],\n [css.includes(\\\"color: #f5fbff\\\"), \\\"light code text\\\"],\n [css.includes(\\\"font-size: 13px\\\") \u0026\u0026 css.includes(\\\"line-height: 19px\\\"), \\\"code block sizing\\\"],\n [css.includes(\\\"toc-link-h3\\\"), \\\"toc h3 class\\\"],\n [css.includes(\\\"sidebar-chevron\\\"), \\\"sidebar chevron class\\\"],\n [css.includes(\\\"font-weight: 500\\\") \u0026\u0026 css.includes(\\\"sidebar-link-active\\\"), \\\"active link weight 500\\\"],\n [css.includes(\\\"border-left: 2px solid var(--color-link)\\\"), \\\"active left border\\\"],\n [css.includes(\\\"text-underline-offset\\\"), \\\"link underline style\\\"],\n [css.includes(\\\"scrollbar-gutter: stable\\\"), \\\"scrollbar gutter\\\"],\n [css.includes(\\\"max-width: 1200px\\\"), \\\"toc breakpoint 1200\\\"],\n [css.match(/\\\\.layout-content h2[^}]*font-size: 24px/s), \\\"h2 24px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-size: 16px/s), \\\"h3 16px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-weight: 700/s), \\\"h3 weight 700\\\"],\n];\nlet pass = true;\nfor (const [ok, name] of checks) {\n if (!ok) { console.error(\\\"FAIL: \\\" + name); pass = false; }\n else { console.log(\\\"PASS: \\\" + name); }\n}\nif (!pass) process.exit(1);\nconsole.log(\\\"\\\\nAll CSS checks passed.\\\");\n\"\n```\n\n## Dont\n- Do not modify any component JS files\n- Do not change the mobile responsive rules (keep mobile padding as-is)\n- Do not remove any CSS rules that are still referenced by components (check before deleting)\n- Do not change the design token variable names, only their values","status":"closed","priority":1,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:25:14.346526+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:31:23.234686+13:00","closed_at":"2026-02-14T22:31:23.234686+13:00","close_reason":"2fda6b5 Applied all 36 CSS changes for Stripe design parity: unified heading colors, updated layout dimensions, improved sidebar/TOC styling, dark code blocks, enhanced typography, and responsive breakpoints","dependencies":[{"issue_id":"docs-150.4","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:25:14.348237+13:00","created_by":"Sharfy Adamantine"}]} +{"id":"docs-1ho","title":"Epic: Adopt scaffold visual design language for docs site","description":"Migrate the documentation site's visual design (fonts, colors, radii, typography, header) to match the hypercerts-scaffold-atproto design language. The scaffold uses Syne for display/headings, Outfit for body text, Geist Mono for code, an OKLCH indigo-tinted neutral palette, 10px base radius, and a refined modern aesthetic. The docs site currently uses system fonts, hex colors (#0570de accent), plain CSS with 4-8px radii, and a light-grey header. This epic updates the CSS custom properties and font loading — it does NOT introduce Tailwind or shadcn. The docs site stays plain CSS. Success: the docs site visually reads as the same brand as the scaffold app.","status":"open","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-20T18:19:37.842151+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:19:37.842151+08:00","labels":["scope:medium"]} +{"id":"docs-1ho.1","title":"Load Syne, Outfit, and Geist Mono fonts","description":"## Files\n- documentation/components/Layout.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\n\n### 1. Add Google Fonts in Layout.js \u003cHead\u003e\nAdd a `\u003clink\u003e` tag inside the existing `\u003cHead\u003e` block to load Syne (400;500;600;700;800), Outfit (300;400;500;600;700), and Geist Mono (400;500) from Google Fonts.\n\nUse this exact URL:\n```\nhttps://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800\u0026family=Outfit:ital,wght@0,300;0,400;0,500;0,600;0,700\u0026family=Geist+Mono:wght@400;500\u0026display=swap\n```\n\nAdd both a `\u003clink rel=\"preconnect\"\u003e` for `fonts.googleapis.com` and `fonts.gstatic.com`, plus the stylesheet link. Place them BEFORE the existing `\u003cmeta\u003e` tags inside `\u003cHead\u003e`.\n\n### 2. Update CSS custom properties in globals.css\nReplace the existing `--font-sans` and `--font-mono` custom properties in the `:root` block:\n\n```css\n--font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n Helvetica, Arial, sans-serif;\n--font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n--font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco,\n Consolas, monospace;\n```\n\nNote: `--font-display` is a NEW custom property. Keep the system font fallbacks.\n\n### 3. Apply the display font to headings\nAdd these rules right after the existing `body { ... }` rule:\n\n```css\nh1, h2, h3, h4, h5, h6,\n.sidebar-section-header {\n font-family: var(--font-display);\n}\n```\n\nThis single rule applies Syne to all headings and sidebar section headers.\n\n## Don't\n- Do NOT remove any existing CSS rules\n- Do NOT change any font sizes, weights, or colors in this task (that is a separate task)\n- Do NOT add next/font — this project uses the Pages Router, use \u003clink\u003e tags\n- Do NOT add fonts to _app.js — they go in Layout.js \u003cHead\u003e\n- Do NOT touch any files other than Layout.js and globals.css","acceptance_criteria":"1. Visiting the docs site shows Outfit for body text (inspect body element, computed font-family starts with Outfit)\n2. All headings (h1-h6) render in Syne (inspect any h2, computed font-family starts with Syne)\n3. Code blocks render in Geist Mono (inspect a \u003ccode\u003e element, computed font-family starts with Geist Mono)\n4. Sidebar section headers render in Syne\n5. The Google Fonts link tag exists in the rendered HTML \u003chead\u003e\n6. Preconnect links exist for fonts.googleapis.com and fonts.gstatic.com\n7. globals.css defines three font custom properties: --font-sans, --font-display, --font-mono\n8. `npm run build` in documentation/documentation/ succeeds without errors","status":"open","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-20T18:19:58.309568+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:19:58.309568+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.1","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:19:58.310671+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.2","title":"Migrate color palette to OKLCH indigo-tinted neutrals","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nReplace the hex color values in the `:root` CSS custom properties with OKLCH equivalents that match the scaffold's indigo-tinted neutral palette (hue ~260). This aligns the docs site with the scaffold's visual identity.\n\n### Replace these custom properties in `:root`:\n\n**Neutrals:**\n```css\n/* OLD → NEW */\n--color-bg: #ffffff; → --color-bg: oklch(0.995 0.001 260);\n--color-bg-subtle: #f6f8fa; → --color-bg-subtle: oklch(0.96 0.005 260);\n--color-border: #ebeef1; → --color-border: oklch(0.91 0.005 260);\n--color-border-strong: #d8dee4; → --color-border-strong: oklch(0.86 0.008 260);\n--color-text-primary: #414552; → --color-text-primary: oklch(0.40 0.015 260);\n--color-text-heading: #1a1b25; → --color-text-heading: oklch(0.20 0.01 260);\n--color-text-title: #1a1b25; → --color-text-title: oklch(0.16 0.005 260);\n--color-text-secondary: #687385;→ --color-text-secondary: oklch(0.55 0.01 260);\n--color-text-sidebar: #414552; → --color-text-sidebar: oklch(0.40 0.015 260);\n```\n\n**Accent / Links — keep the blue but express in OKLCH:**\n```css\n--color-link: #0570de; → --color-link: oklch(0.50 0.18 260);\n--color-link-hover: #0055bc; → --color-link-hover: oklch(0.43 0.19 260);\n--color-accent: #0570de; → --color-accent: oklch(0.50 0.18 260);\n```\n\n**Interaction colors (misc section):**\n```css\n--hover-bg: #f6f8fa; → --hover-bg: oklch(0.96 0.005 260);\n--active-bg: #f0f4ff; → --active-bg: oklch(0.95 0.015 260);\n--focus-ring: 0 0 0 4px rgba(5, 112, 222, 0.36); → --focus-ring: 0 0 0 4px oklch(0.50 0.18 260 / 0.36);\n```\n\n**Callout colors — keep the hues but express in OKLCH:**\n```css\n--color-info: #0570de; → --color-info: oklch(0.50 0.18 260);\n--color-info-bg: #f0f7ff; → --color-info-bg: oklch(0.96 0.02 260);\n--color-warning: #c84801; → --color-warning: oklch(0.55 0.17 55);\n--color-warning-bg: #fef9f0; → --color-warning-bg: oklch(0.97 0.02 80);\n--color-danger: #df1b41; → --color-danger: oklch(0.52 0.22 25);\n--color-danger-bg: #fef0f4; → --color-danger-bg: oklch(0.97 0.02 15);\n--color-success: #228403; → --color-success: oklch(0.52 0.17 145);\n--color-success-bg: #f0fef0; → --color-success-bg: oklch(0.97 0.03 145);\n```\n\n### Also update these hardcoded colors in other selectors:\n\n1. `.layout-header` background: change `#f6f8fa` → `oklch(0.985 0.002 260)` (scaffold's background tone for the header — near-white, matching the page body but with a faint warmth)\n\n2. `.breadcrumbs-separator` color: change `#a3acba` → `oklch(0.70 0.01 260)`\n\n3. `.layout-content blockquote` border-left color: change `#c0c8d2` → `oklch(0.80 0.01 260)`\n\n### DO NOT change these hardcoded colors (they are code-block-specific and should stay):\n- `#011627` (Night Owl background)\n- `#0d2137` (code block header)\n- `#1e3a5f` (code block border)\n- `#8899aa`, `#556677`, `#aabbcc` (code block UI elements)\n- Any `rgba(255, 255, 255, ...)` scrollbar colors inside code blocks\n\n## Don't\n- Do NOT change font families, font sizes, font weights, or spacing\n- Do NOT change the code block color scheme (Night Owl)\n- Do NOT touch Layout.js or any other files\n- Do NOT add dark mode (separate concern)\n- Do NOT change the LANGUAGE_META colors in CodeBlock.js\n- Do NOT add new CSS rules — only modify existing property values","acceptance_criteria":"1. All `:root` color custom properties use oklch() syntax (no hex values remain for tokens listed above)\n2. The page background is near-white with a faint blue tint (visually similar to before but not pure white)\n3. Links are still blue and visually similar to before\n4. Callout boxes still show 4 distinct colors (blue info, orange warning, red danger, green success)\n5. Code blocks are unchanged (Night Owl dark blue background preserved)\n6. Header background is updated to oklch value\n7. Breadcrumb separator and blockquote border use oklch values\n8. `npm run build` in documentation/documentation/ succeeds without errors\n9. The site loads correctly in Chrome 111+ and Safari 15.4+ (oklch browser support baseline)","status":"open","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-20T18:20:31.538843+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:20:31.538843+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:31.54053+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:20:31.542591+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.3","title":"Update border radii and spacing to match scaffold","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate the border radius custom properties and a few spacing values to match the scaffold's more rounded, modern aesthetic.\n\n### 1. Update radius tokens in `:root`\n```css\n/* OLD → NEW */\n--radius-sm: 4px; → --radius-sm: 6px;\n--radius-md: 6px; → --radius-md: 8px;\n--radius-lg: 8px; → --radius-lg: 10px;\n```\n\nAlso add a new token after `--radius-lg`:\n```css\n--radius-xl: 14px;\n```\n\n### 2. Update the code block border-radius\nIn `.codeblock`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\nIn the fallback rule `.layout-content pre:not(.codeblock-pre)`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\n### 3. Update card-link border-radius\nIn `.card-link`, change:\n```css\nborder-radius: var(--radius-lg);\n```\nThis already uses the token — it will automatically pick up the new 10px value. No change needed.\n\n### 4. Update pagination-link border-radius\nIn `.pagination-link`, it already uses `var(--radius-lg)` — will pick up automatically.\n\n## Don't\n- Do NOT change any font, color, or typography properties\n- Do NOT change spacing tokens (--space-*) — they are fine as-is\n- Do NOT change the code block internal padding or header styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. --radius-sm is 6px, --radius-md is 8px, --radius-lg is 10px, --radius-xl is 14px in :root\n2. Code blocks have 10px border radius (inspect .codeblock element)\n3. Card links have 10px border radius\n4. Sidebar links have 8px border radius (--radius-md)\n5. Inline code still has rounded corners (uses --radius-sm = 6px now)\n6. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:20:48.238131+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:20:48.238131+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.3","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:48.239264+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.4","title":"Refine heading typography to match scaffold display style","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate heading styles to match the scaffold's Syne display typography conventions. The scaffold uses tighter letter-spacing and bolder heading hierarchy with Syne. These changes assume docs-1ho.1 (font loading) is already applied.\n\n### 1. Update `.layout-content h1`\nAdd `letter-spacing: -0.02em;` (tracking-tight in scaffold convention).\nKeep all other properties (font-size: 32px, font-weight: 700, etc.) unchanged.\n\n### 2. Update `.layout-content h2`\nAdd `letter-spacing: -0.01em;`.\nKeep all other properties unchanged.\n\n### 3. Update `.sidebar-section-header`\nChange from:\n```css\n.sidebar-section-header {\n font-size: 14px;\n font-weight: 600;\n text-transform: uppercase;\n color: var(--color-text-heading);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\nTo:\n```css\n.sidebar-section-header {\n font-size: 11px;\n font-weight: 700;\n text-transform: uppercase;\n letter-spacing: 0.08em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\n\nThis matches the scaffold's convention: sidebar section headers are smaller (11px), bolder (700), wider-tracked (0.08em), and use secondary color to feel like category labels rather than content headings.\n\n### 4. Update `.toc-title`\nChange `font-weight: 700` → `font-weight: 600` and add `font-family: var(--font-display);`\n\nThis gives the TOC \"On this page\" label the Syne display treatment.\n\n## Don't\n- Do NOT change font-size on h1, h2, h3, h4 (only add letter-spacing)\n- Do NOT change any colors (that is the colors task)\n- Do NOT change body text or paragraph styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. H1 has letter-spacing: -0.02em (inspect computed style)\n2. H2 has letter-spacing: -0.01em\n3. Sidebar section headers are 11px, font-weight 700, letter-spacing 0.08em, color is --color-text-secondary\n4. TOC title uses Syne (font-family: var(--font-display))\n5. No heading font sizes have changed from their current values\n6. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:21:05.00645+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:05.00645+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:05.008011+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:05.009956+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.5","title":"Add antialiased rendering and body font-weight","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nThe scaffold uses `antialiased` font rendering and Outfit at weight 400 for body text. The docs site already has `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` on body — but Outfit renders slightly differently than system fonts at the default weight. Add `font-weight: 400;` explicitly to the `body` rule to ensure consistent rendering with Outfit.\n\n### 1. In the `body { ... }` rule, add:\n```css\nfont-weight: 400;\n```\nPlace it after `font-size: 16px;`.\n\n### 2. Update the existing `body` line-height from `1.65` to `1.6`\nThe scaffold uses tighter line-height with Outfit. Change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n### 3. Update list item line-height to match\nIn `.layout-content article li`, change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n## Don't\n- Do NOT change any font-family properties\n- Do NOT change any colors\n- Do NOT change heading styles\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. Body element has font-weight: 400 in computed styles\n2. Body element has line-height: 1.6\n3. List items have line-height: 1.6\n4. Text renders with antialiased smoothing (already present, verify not removed)\n5. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-20T18:21:19.242335+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:19.242335+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:19.243605+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:19.245486+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-390","title":"Epic: Replace speculative blockchain/tokenization language with freeze-then-fund model across all docs","status":"closed","priority":1,"issue_type":"epic","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:19:57.096114+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T19:52:57.976277+13:00","closed_at":"2026-02-16T19:52:57.976277+13:00","close_reason":"Closed"} {"id":"docs-390.1","title":"Rewrite architecture/overview.md: replace blockchain ownership layer with freeze-then-fund model","description":"## Files\n- documentation/pages/architecture/overview.md (modify)\n\n## What to do\n\nUpdate all references to blockchain-based tokenization/ownership to reflect that:\n1. The tokenization layer has NOT been developed yet — it is TBD\n2. The theory and architecture are correct — freeze records, anchor on-chain, then fund\n3. The docs should present this as the intended design, not as something that exists today\n\nThe freeze-then-fund model:\n1. A hypercert starts as mutable ATProto records (activity claim + evidence + evaluations etc.)\n2. Before a hypercert can be funded, its ATProto records must be **frozen** — a snapshot of the current state is taken and anchored on-chain. This creates an immutable reference point.\n3. The reason: a funder must know exactly what they are funding. If the cert contents can still change after funding, the funder might end up paying for something different than what they signed up for.\n4. Once frozen and anchored on-chain, the hypercert can be listed for funding.\n5. Evaluations and evidence can still accumulate AFTER freezing — they are separate records that reference the frozen claim. But the core claim itself is immutable once frozen.\n\n### IMPORTANT FRAMING GUIDANCE\n- Do NOT strip out the blockchain/tokenization concept — the theory is right and the architecture is sound\n- DO make clear that the tokenization layer hasn't been built yet — it's TBD\n- Frame it as: \"the intended design is X\" or \"the planned approach is X\" — not as if it's live\n- Use phrases like \"the tokenization layer is not yet implemented\", \"this is the planned design\", \"the on-chain mechanisms are being designed\"\n- Keep the two-layer architecture (data layer + ownership/funding layer) — it's the right design\n- When describing how tokenization/funding WILL work, use future tense or \"planned\" language\n- The freeze-then-fund concept is the KEY insight to convey: you must freeze the cert before allowing funding\n\n### Specific changes needed:\n\n**Line 8:** Change \"combines AT Protocol for data portability with blockchain for ownership guarantees\" → something like \"combines AT Protocol for data portability with planned on-chain anchoring for ownership and funding guarantees.\" Make clear this is the design, not yet implemented.\n\n**Line 18 (Ownership Layer description):** Rewrite. The ownership layer is planned but not yet built. The intended design: frozen hypercert snapshots will be anchored on-chain so they can be funded. A hypercert cannot be funded while its contents are still changing — freezing ensures funders know exactly what they are paying for. Make clear this layer is TBD.\n\n**Lines 20-31 (stack diagram):** Update the bottom layer label. Add \"(planned)\" or similar to indicate it's not yet built.\n\n**Lines 63-81 (Ownership Layer Deep Dive):** Rewrite this section to describe the PLANNED design:\n- \"Anchoring\": Describe the planned approach — freezing the ATProto record state and anchoring the snapshot on-chain.\n- \"Tokenization\": Explain the planned approach — the specific on-chain mechanism (token standard, chain choice) is being designed. The concept: freeze the cert, anchor it, then enable funding.\n- \"Funding Mechanisms\": Keep the general concepts (direct purchase, retroactive funding, etc.) but frame as planned/intended, not implemented.\n- \"Multi-Chain Support\": Frame as intended design, not yet determined.\n\n**Lines 83-112 (How the Layers Connect):** Rewrite to describe the planned design:\n- The bridge will be: ATProto records are frozen, the snapshot CID is anchored on-chain, and funding operates against that frozen state.\n- Keep the cross-layer example but frame as \"how this will work\" not \"how this works.\"\n\n**Lines 114-136 (Key Design Decisions):**\n- \"Why Not Fully On-Chain?\" — Keep as-is, still valid.\n- \"Why Not Fully Off-Chain?\" — Rewrite to emphasize: without on-chain anchoring, there's no way to guarantee that what a funder pays for won't change. Freezing and anchoring provides the immutability guarantee.\n- \"Why This Separation?\" — Update to mention freeze-then-fund as the key planned mechanism.\n\n**Lines 138-148 (What This Enables):**\n- Frame enabled use cases as what the design WILL enable once the tokenization layer is built.\n\n### Key terminology:\n- Keep \"tokenization\" as a concept but mark as \"planned\" / \"not yet implemented\" / \"TBD\"\n- Use \"freeze\" / \"frozen\" / \"freezing\" to describe the new concept\n- Use future tense or \"planned\" language for anything on-chain\n- Keep \"funding\" language — the concept is real\n\n### Tone:\n- The architecture is sound, the theory is right\n- The tokenization layer just hasn't been built yet\n- Be clear about what exists (ATProto data layer) vs what's planned (on-chain ownership/funding layer)\n\n## Test\ngrep -q 'not yet\\|TBD\\|being designed\\|planned\\|will be' documentation/pages/architecture/overview.md \u0026\u0026 \\\ngrep -q 'freez' documentation/pages/architecture/overview.md \u0026\u0026 \\\ngrep -q 'funder.*know\\|know.*fund\\|change.*after\\|cannot.*funded.*changing\\|can.t.*funded.*chang\\|exactly what' documentation/pages/architecture/overview.md \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Remove the blockchain/tokenization concept entirely — the theory is right, keep it as the planned design\n- Present tokenization as if it's already implemented/live\n- Invent specific smart contract details or token standards that don't exist\n- Change the Data Layer section (lines 33-61) — that's accurate as-is\n- Change the \"Why ATProto Over IPFS\" section (126-130) — that's accurate","status":"closed","priority":1,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:20:42.512677+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T12:32:03.352974+13:00","closed_at":"2026-02-16T12:32:03.352974+13:00","close_reason":"9055496 Rewrite architecture/overview.md to reflect freeze-then-fund model and planned tokenization layer","labels":["scope:medium"],"dependencies":[{"issue_id":"docs-390.1","depends_on_id":"docs-390","type":"parent-child","created_at":"2026-02-16T12:20:42.514231+13:00","created_by":"sharfy-test.climateai.org"}]} {"id":"docs-390.2","title":"Rewrite architecture/data-flow-and-lifecycle.md: replace Stage 5 blockchain funding with freeze-then-fund","description":"## Files\n- documentation/pages/architecture/data-flow-and-lifecycle.md (modify)\n\n## What to do\n\nUpdate blockchain-centric language in the lifecycle doc. Key framing:\n1. The tokenization layer has NOT been developed yet — it is TBD\n2. The theory and architecture are correct — freeze records, anchor on-chain, then fund\n3. The docs should present this as the intended design, not as something that exists today\n\nThe freeze-then-fund model: before a hypercert can be funded, its ATProto records must be frozen (snapshotted and anchored on-chain). This protects funders — they need to know exactly what they're funding, and the cert contents must not change after funding.\n\n### IMPORTANT FRAMING GUIDANCE\n- Do NOT strip out the blockchain/tokenization concept — the theory is right and the architecture is sound\n- DO make clear that the tokenization layer hasn't been built yet — it's TBD\n- Frame it as: \"the intended design is X\" or \"the planned approach is X\" — not as if it's live\n- Use phrases like \"the tokenization layer is not yet implemented\", \"this is the planned design\", \"the on-chain mechanisms are being designed\"\n- When describing how tokenization/funding WILL work, use future tense or \"planned\" language\n- The freeze-then-fund concept is the KEY insight to convey\n\n### Specific changes:\n\n**Line 16 (Enrichment):** Change \"Rights records define what token holders receive\" → \"Rights records define what funders or stakeholders receive.\" (The concept of rights is correct, just don't assume tokens exist yet.)\n\n**Line 22 (Funding stage summary):** Rewrite. Current text presents tokenization as live. New text should describe the planned design: Before funding, the hypercert's ATProto records will be frozen — a cryptographic snapshot taken and anchored on-chain. This ensures funders know exactly what they are paying for. The cert's core content cannot change after freezing. The specific on-chain funding mechanisms are being designed.\n\n**Line 24 (Accumulation):** Update to reflect planned design. Evaluations and evidence continue accumulating around the frozen claim.\n\n**Line 29 (diagram):** Change \"Blockchain\" under Funding to \"On-chain (planned)\"\n\n**Line 69 (Rights records):** Change \"define what token holders receive\" → \"define what funders or stakeholders receive\"\n\n**Lines 146-181 (Stage 5: Funding \u0026 Ownership):** Rewrite this section to describe the PLANNED design:\n\n- **Anchoring:** Describe the planned approach — when a hypercert is ready for funding, its current ATProto state will be frozen. The snapshot CID is anchored on-chain. The reason: a funder must know exactly what they are funding.\n\n- **Tokenization → rename to \"Freezing and Immutability\":** Explain the planned concept. Once frozen, the core activity claim cannot be modified. Evidence and evaluations can still accumulate. The specific on-chain representation (token standard, contract design) is being designed. Note: the tokenization layer is not yet implemented, but the theory is sound.\n\n- **Funding Mechanisms:** Keep the general concepts but frame as planned. Various funding models are intended, including direct funding, retroactive funding, and impact certificates. The specific mechanisms are being designed.\n\n- **Multi-Chain Support:** Frame as intended design. The protocol plans to be chain-agnostic but specifics are TBD.\n\n- **Diagram:** Update to reflect planned state. Replace \"Token Contract\" / \"Token ID\" with planned equivalents like \"Frozen Snapshot\" / \"CID: bafyrei...\"\n\n**Lines 199-205 (Stage 6 - Ownership Transfers / Long-Term Value):**\n- Reframe around the planned design. The frozen on-chain anchor will persist independently. Remove language that presents token transfers as live. Frame as intended future behavior.\n\n**Line 212 (diagram):** Change \"Blockchain\" labels to \"On-chain (planned)\"\n\n### Key terminology:\n- Keep \"tokenization\" as a concept but mark as \"planned\" / \"not yet implemented\" / \"TBD\"\n- Use \"freeze\" / \"frozen\" / \"freezing\" to describe the new concept\n- \"funders\" instead of \"token holders\" where referring to people who fund\n- Use future tense or \"planned\" language for anything on-chain\n- Keep \"on-chain\" — blockchain IS the plan\n\n## Test\ngrep -q 'not yet\\|TBD\\|being designed\\|planned\\|will be' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\ngrep -q 'freez' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\ngrep -q 'cannot.*change\\|must not.*change\\|exactly what.*fund\\|know.*what.*pay\\|frozen' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\n! grep -q 'token holder' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Remove the blockchain/tokenization concept entirely — the theory is right, keep it as the planned design\n- Present tokenization as if it's already implemented/live\n- Change Stages 1-4 (Creation, Enrichment, Evaluation, Discovery) unless they contain token holder language\n- Invent smart contract details\n- Change the Cross-PDS References section (lines 215-234) — that's accurate\n- Change the \"What This Flow Enables\" section (lines 236-246) unless it has token language","status":"closed","priority":1,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:21:20.091221+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T12:31:55.410818+13:00","closed_at":"2026-02-16T12:31:55.410818+13:00","close_reason":"5d8ba48 Replace Stage 5 blockchain funding with freeze-then-fund model","labels":["scope:medium"],"dependencies":[{"issue_id":"docs-390.2","depends_on_id":"docs-390","type":"parent-child","created_at":"2026-02-16T12:21:20.092158+13:00","created_by":"sharfy-test.climateai.org"}]} @@ -36,9 +42,9 @@ {"id":"docs-dfq.6","title":"Transition and hover state polish","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nAdd smooth transitions and refined hover states throughout the site, matching Stripe docs interaction patterns. All changes are CSS-only.\n\n### 1. Global transition timing\nAdd a CSS custom property for the standard transition in the `:root` design tokens section (around line 69, before the closing `}`):\n\n```css\n --transition-fast: 150ms ease;\n --transition-normal: 200ms cubic-bezier(0, 0.09, 0.4, 1);\n```\n\n### 2. Sidebar link transitions\nUpdate the existing `.sidebar-link` rule (line ~214-225). Add/modify the transition property:\n\nChange FROM:\n```css\n transition: background 0.1s ease;\n```\n\nChange TO:\n```css\n transition: background var(--transition-fast), color var(--transition-fast);\n```\n\n### 3. Sidebar active indicator\nAdd a left border indicator for the active sidebar link. Modify `.sidebar-link-active` (line ~233-237):\n\nChange FROM:\n```css\n.sidebar-link-active {\n font-weight: 600;\n color: var(--color-text-title);\n background: var(--hover-bg);\n}\n```\n\nChange TO:\n```css\n.sidebar-link-active {\n font-weight: 600;\n color: var(--color-link);\n background: var(--active-bg);\n border-left: 2px solid var(--color-link);\n padding-left: calc(var(--space-3) - 2px);\n}\n```\n\nAlso update `a.sidebar-link-active:hover` (line ~239-242):\n\nChange FROM:\n```css\na.sidebar-link-active:hover {\n background: var(--hover-bg);\n color: var(--color-text-title);\n}\n```\n\nChange TO:\n```css\na.sidebar-link-active:hover {\n background: var(--active-bg);\n color: var(--color-link);\n}\n```\n\n### 4. Pagination hover enhancement\nUpdate the `.pagination-link` transition (line ~354):\n\nChange FROM:\n```css\n transition: border-color 0.15s ease, box-shadow 0.15s ease;\n```\n\nChange TO:\n```css\n transition: border-color var(--transition-normal), box-shadow var(--transition-normal), transform var(--transition-normal);\n```\n\nAdd a subtle lift on hover. Update `.pagination-link:hover` (line ~357-361):\n\nChange FROM:\n```css\n.pagination-link:hover {\n border-color: var(--color-link);\n box-shadow: 0 1px 4px rgba(5, 112, 222, 0.08);\n text-decoration: none;\n}\n```\n\nChange TO:\n```css\n.pagination-link:hover {\n border-color: var(--color-link);\n box-shadow: 0 2px 8px rgba(5, 112, 222, 0.12);\n text-decoration: none;\n transform: translateY(-1px);\n}\n```\n\n### 5. TOC link transitions\nUpdate the `.toc-link` transition (line ~315):\n\nChange FROM:\n```css\n transition: color 0.15s ease, border-color 0.15s ease;\n```\n\nChange TO:\n```css\n transition: color var(--transition-fast), border-color var(--transition-fast);\n```\n\n### 6. Callout subtle left border animation\nAdd a transition to callout on hover:\n\n```css\n.callout {\n transition: box-shadow var(--transition-normal);\n}\n\n.callout:hover {\n box-shadow: 0 1px 4px rgba(0, 0, 0, 0.04);\n}\n```\n\nAdd these rules after the existing `.callout` rule (line ~533-537). Do NOT modify the existing `.callout` rule — add the transition property to a NEW `.callout` rule block that will merge via cascade, OR add the `transition` property directly into the existing `.callout` block.\n\n## Test\n```bash\ncd documentation \u0026\u0026 npm run build\n```\nMust exit 0. Additionally:\n```bash\ngrep \"transition-fast\" documentation/styles/globals.css \u0026\u0026 echo \"Tokens OK\"\ngrep \"transition-normal\" documentation/styles/globals.css \u0026\u0026 echo \"Tokens OK\"\ngrep \"translateY\" documentation/styles/globals.css \u0026\u0026 echo \"Pagination lift OK\"\ngrep \"border-left.*solid.*color-link\" documentation/styles/globals.css \u0026\u0026 echo \"Active indicator OK\"\n```\nAll four checks must pass.\n\n## Dont\n- Do not add page transition animations (route changes) — that requires JavaScript\n- Do not modify any JavaScript files\n- Do not change colors or font sizes\n- Do not add animation keyframes — only use CSS transitions\n- Do not modify the mobile responsive section","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T14:25:54.998064+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T20:03:35.256599+13:00","closed_at":"2026-02-14T20:03:35.256599+13:00","close_reason":"Implemented all transition and hover state polish: added transition timing variables, updated sidebar/TOC/pagination transitions, added active indicator with border-left, and callout hover effects","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-dfq.6","depends_on_id":"docs-dfq","type":"parent-child","created_at":"2026-02-14T14:25:54.998941+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-dfq.7","title":"Landing page card-style navigation links","description":"## Files\n- documentation/pages/index.md (modify)\n- documentation/components/CardLink.js (create)\n- documentation/markdoc/tags/card-link.markdoc.js (create)\n- documentation/pages/_app.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\nAdd card-style navigation links to the landing page, similar to Stripe docs landing pages that have categorized link cards with titles, descriptions, and hover effects.\n\n### 1. Create `documentation/components/CardLink.js`\n\nA card component for navigation links:\n\n```jsx\nimport Link from \"next/link\";\n\nexport function CardLink({ title, href, children }) {\n return (\n \u003cLink href={href} className=\"card-link\"\u003e\n \u003cspan className=\"card-link-title\"\u003e{title}\u003c/span\u003e\n {children \u0026\u0026 \u003cspan className=\"card-link-desc\"\u003e{children}\u003c/span\u003e}\n \u003cspan className=\"card-link-arrow\"\u003e→\u003c/span\u003e\n \u003c/Link\u003e\n );\n}\n```\n\n### 2. Create `documentation/markdoc/tags/card-link.markdoc.js`\n\nRegister the CardLink as a Markdoc tag:\n\n```js\nexport default {\n render: \"CardLink\",\n attributes: {\n title: { type: String, required: true },\n href: { type: String, required: true },\n },\n};\n```\n\n### 3. Modify `documentation/pages/_app.js`\n\nAdd import and register:\n\n```js\nimport { CardLink } from \"../components/CardLink\";\n```\n\nAdd to components object:\n```js\nconst components = {\n Callout,\n Columns,\n Column,\n Figure,\n Heading, // (if heading task is done, otherwise omit)\n CardLink,\n};\n```\n\n**IMPORTANT**: The components object may already contain `Heading` if task docs-dfq.2 was completed first. If `Heading` is already there, keep it. If not, do NOT add it — only add `CardLink`.\n\n### 4. Add CSS to `documentation/styles/globals.css`\n\nAdd a new section after the Figure component styles (around line ~597):\n\n```css\n/* ===== Component: CardLink ===== */\n.card-link {\n display: block;\n padding: var(--space-4) var(--space-5);\n border: 1px solid var(--color-border);\n border-radius: var(--radius-lg);\n text-decoration: none;\n transition: border-color 0.2s ease, box-shadow 0.2s ease, transform 0.2s ease;\n position: relative;\n margin-bottom: var(--space-3);\n}\n\n.card-link:hover {\n border-color: var(--color-link);\n box-shadow: 0 2px 8px rgba(5, 112, 222, 0.1);\n text-decoration: none;\n transform: translateY(-1px);\n}\n\n.card-link-title {\n display: block;\n font-size: 15px;\n font-weight: 600;\n color: var(--color-link);\n margin-bottom: var(--space-1);\n}\n\n.card-link-desc {\n display: block;\n font-size: 14px;\n color: var(--color-text-secondary);\n line-height: 1.5;\n}\n\n.card-link-arrow {\n position: absolute;\n right: var(--space-4);\n top: 50%;\n transform: translateY(-50%);\n color: var(--color-link);\n font-size: 16px;\n opacity: 0;\n transition: opacity 0.15s ease, transform 0.15s ease;\n}\n\n.card-link:hover .card-link-arrow {\n opacity: 1;\n transform: translateY(-50%) translateX(2px);\n}\n```\n\n### 5. Modify `documentation/pages/index.md`\n\nAdd a \"Quick Start\" section with card links after the existing content. Append to the end of the file:\n\n```markdown\n\n## Quick Start\n\n{% card-link title=\"Why We're Building Hypercerts\" href=\"/getting-started/why-were-building-hypercerts\" %}\nUnderstand the motivation behind the hypercerts protocol\n{% /card-link %}\n\n{% card-link title=\"Introduction to Impact Claims\" href=\"/getting-started/introduction-to-impact-claims\" %}\nLearn about impact claims and how they work\n{% /card-link %}\n\n{% card-link title=\"The Hypercerts Infrastructure\" href=\"/getting-started/the-hypercerts-infrastructure\" %}\nExplore the technical architecture\n{% /card-link %}\n\n{% card-link title=\"Introduction to Lexicons\" href=\"/lexicons/introduction-to-lexicons\" %}\nUnderstand the data schemas that power hypercerts\n{% /card-link %}\n```\n\n## Test\n```bash\ncd documentation \u0026\u0026 npm run build\n```\nMust exit 0. Additionally:\n```bash\ntest -f documentation/components/CardLink.js \u0026\u0026 echo \"Component OK\"\ntest -f documentation/markdoc/tags/card-link.markdoc.js \u0026\u0026 echo \"Tag OK\"\ngrep \"CardLink\" documentation/pages/_app.js \u0026\u0026 echo \"Registration OK\"\ngrep \"card-link\" documentation/styles/globals.css \u0026\u0026 echo \"CSS OK\"\ngrep \"card-link\" documentation/pages/index.md \u0026\u0026 echo \"Content OK\"\n```\nAll five checks must pass.\n\n## Dont\n- Do not modify existing content on the landing page — only append new content\n- Do not remove the existing columns/figures layout\n- Do not use any external icon libraries\n- Do not modify navigation.js\n- Do not add more than 4 card links","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T14:26:17.319286+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T20:07:08.03882+13:00","closed_at":"2026-02-14T20:07:08.03882+13:00","close_reason":"9969a9b Landing page card-style navigation links","labels":["scope:small"],"dependencies":[{"issue_id":"docs-dfq.7","depends_on_id":"docs-dfq","type":"parent-child","created_at":"2026-02-14T14:26:17.320306+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-dfq.8","title":"Integration: verify all refinements build and render correctly","description":"## Files\n- (no files to create/modify — verification only)\n\n## What to do\nAfter all other tasks in Epic 10 are complete, verify the full integration:\n\n1. Run `cd documentation \u0026\u0026 npm run build` — must exit 0 with no errors\n2. Verify all 17 pages are in the static export\n3. Spot-check that no CSS conflicts exist between the various refinements\n4. Verify the landing page renders with card links\n5. Verify breadcrumbs appear on non-home pages\n\n## Test\n```bash\ncd documentation \u0026\u0026 npm run build 2\u003e\u00261 | grep -c \"●\" | xargs test 17 -eq\n```\nMust show exactly 17 SSG pages.\n\n```bash\ncd documentation \u0026\u0026 npm run build\n```\nMust exit 0.\n\n## Dont\n- Do not modify any files\n- This is a verification-only task","status":"closed","priority":1,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T14:26:25.677169+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T20:10:10.53275+13:00","closed_at":"2026-02-14T20:10:10.53275+13:00","close_reason":"Closed","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq","type":"parent-child","created_at":"2026-02-14T14:26:25.678222+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.1","type":"blocks","created_at":"2026-02-14T14:26:31.650675+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.2","type":"blocks","created_at":"2026-02-14T14:26:31.749901+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.3","type":"blocks","created_at":"2026-02-14T14:26:31.849858+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.4","type":"blocks","created_at":"2026-02-14T14:26:31.950473+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.5","type":"blocks","created_at":"2026-02-14T14:26:32.047374+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.6","type":"blocks","created_at":"2026-02-14T14:26:32.141096+13:00","created_by":"Sharfy Adamantine"},{"issue_id":"docs-dfq.8","depends_on_id":"docs-dfq.7","type":"blocks","created_at":"2026-02-14T14:26:32.236529+13:00","created_by":"Sharfy Adamantine"}]} -{"id":"docs-jss","title":"Epic: Add project-level README.md and DEVELOPMENT.md","description":"The documentation project lacks the standard project-level README.md and DEVELOPMENT.md files that our other repos (like hypercerts-scaffold-atproto) have. This epic adds both files following the same structure and style: comprehensive README with quick start, prerequisites, project structure, architecture; and DEVELOPMENT.md with local dev workflow, content authoring guide, Markdoc conventions, contributing, and troubleshooting. Success: a new contributor can clone the repo, run the docs site locally, and add a new page — all by reading README + DEVELOPMENT only.","status":"open","priority":2,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-20T18:12:19.646036+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:12:19.646036+08:00","labels":["scope:medium"]} -{"id":"docs-jss.1","title":"Create README.md at project root","description":"## Files\n- README.md (create)\n\n## What to do\nCreate a comprehensive README.md at the repo root following the structure and style of hypercerts-scaffold-atproto/README.md. The file must include these sections in order:\n\n1. **Title \u0026 description** — \"Hypercerts Documentation\" heading. One paragraph: this is the official documentation site for the Hypercerts protocol, built with Next.js and Markdoc, deployed on Vercel.\n\n2. **Prerequisites** — Node.js 20+, npm (not pnpm — the project uses npm per vercel.json and package-lock.json).\n\n3. **Quick Start** — Clone, cd documentation/documentation, npm install, npm run dev. Note the nested directory structure (the actual Next.js app lives in documentation/documentation/).\n\n4. **Project Structure** — ASCII tree showing:\n```\n├── documentation/ # Next.js documentation site\n│ ├── components/ # React components (Layout, Sidebar, CodeBlock, etc.)\n│ ├── lib/ # Navigation config and helpers\n│ ├── markdoc/ # Markdoc tag and node definitions\n│ │ ├── nodes/ # Custom node renderers (fence, heading)\n│ │ └── tags/ # Custom tags (callout, card-link, columns, figure)\n│ ├── pages/ # Documentation content (.md files)\n│ │ ├── architecture/\n│ │ ├── core-concepts/\n│ │ ├── ecosystem/\n│ │ ├── getting-started/\n│ │ ├── lexicons/\n│ │ ├── reference/\n│ │ └── tools/\n│ ├── public/ # Static assets\n│ └── styles/ # CSS\n├── heartbeads-agents/ # (reserved)\n├── AGENTS.md # Agent workflow instructions\n└── .beads/ # Issue tracking\n```\n\n5. **Content Sections** — Table listing the 7 doc sections (Get Started, Core Concepts, Tools, Architecture, Reference/Lexicons, Ecosystem \u0026 Vision) with one-line descriptions, matching the style of the scaffold README tables.\n\n6. **Deployment** — State that the site is deployed on Vercel. The build command is `next build --webpack`, install command is `npm install`. Static export via `output: \"export\"` in next.config.js.\n\n7. **Learn More** — Links to: Hypercerts website (https://hypercerts.org), ATProto docs (https://atproto.com/docs), Markdoc docs (https://markdoc.dev), Next.js docs (https://nextjs.org/docs), DEVELOPMENT.md for contributor guide.\n\n## Don't\n- Do NOT mention pnpm — this project uses npm\n- Do NOT include any authentication, OAuth, or SDK content (this is a docs site, not an application)\n- Do NOT copy scaffold-specific sections (environment variables, Redis, JWK keys, etc.)\n- Do NOT add a License section (there is none currently)\n- Keep it under 150 lines","acceptance_criteria":"1. README.md exists at /Users/david/Projects/gainforest/documentation/README.md\n2. Contains all 7 sections listed in spec: title, prerequisites, quick start, project structure, content sections, deployment, learn more\n3. Quick Start instructions work: cd documentation/documentation \u0026\u0026 npm install \u0026\u0026 npm run dev starts the dev server\n4. References npm (not pnpm) throughout\n5. Project structure ASCII tree accurately reflects actual directory layout\n6. No scaffold-specific content (no Redis, OAuth, JWK, SDK references)\n7. File is under 150 lines\n8. All links in Learn More section are valid URLs","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-20T18:12:47.807873+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:12:47.807873+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-jss.1","depends_on_id":"docs-jss","type":"parent-child","created_at":"2026-02-20T18:12:47.809207+08:00","created_by":"einstein.climateai.org"}]} -{"id":"docs-jss.2","title":"Create DEVELOPMENT.md at project root","description":"## Files\n- DEVELOPMENT.md (create)\n\n## What to do\nCreate a comprehensive DEVELOPMENT.md at the repo root following the structure and style of hypercerts-scaffold-atproto/DEVELOPMENT.md. The file must include these sections in order:\n\n1. **Local Development Workflow** heading, then:\n - **Prerequisites** — Node.js 20+, npm, Git\n - **First-time Setup** — Step-by-step: clone, cd documentation/documentation, npm install, npm run dev, open http://localhost:3000. Note the nested directory structure.\n - **Daily Development** — Just `npm run dev` in the documentation/documentation/ directory.\n - **Build for production** — `npm run build` (produces static export in `out/` directory).\n\n2. **Adding Documentation Pages** — This is the content authoring guide:\n - Explain that pages are Markdoc files (.md) in `documentation/pages/`\n - File location determines URL path (e.g., `pages/getting-started/quickstart.md` → `/getting-started/quickstart`)\n - Every page needs YAML frontmatter with `title` (required) and `description` (optional)\n - Show a template:\n ```markdown\n ---\n title: Page Title\n description: One-line description.\n ---\n\n # Page Title\n\n Content goes here.\n ```\n - After creating a page, add it to the navigation in `documentation/lib/navigation.js`\n - Explain navigation.js structure briefly: top-level items have `title` + `path`, sections have `section` + `children` array, nesting is supported\n\n3. **Markdoc Custom Tags** — List available custom tags with usage examples:\n - `{% callout type=\"note|warning|caution\" %}...{% /callout %}` — callout boxes\n - `{% card-link title=\"...\" href=\"...\" %}...{% /card-link %}` — linked cards\n - `{% columns %}{% column %}...{% /column %}{% column %}...{% /column %}{% /columns %}` — multi-column layout\n - `{% figure src=\"...\" alt=\"...\" caption=\"...\" /%}` — images with captions\n\n4. **Project Architecture** — Brief explanation:\n - Next.js with Markdoc plugin for static site generation\n - `output: \"export\"` produces fully static HTML (no server needed)\n - `pageExtensions: [\"md\", \"mdoc\", \"js\", \"jsx\", \"ts\", \"tsx\"]` — Markdoc files are treated as pages\n - Components in `components/` provide the layout shell (Layout.js), sidebar navigation (Sidebar.js), syntax highlighting (CodeBlock.js), breadcrumbs, etc.\n\n5. **Troubleshooting** — Common issues:\n - \"Module not found\" → run `npm install`\n - Page not appearing in sidebar → check navigation.js\n - Markdoc syntax errors → check tag matching ({% tag %}...{% /tag %})\n - Build fails → ensure Node.js 20+\n\n6. **Contributing** — Follow the same structure as the scaffold:\n - Fork, branch, make changes, test with `npm run build`, open PR\n - Content PRs: new/updated .md files + navigation.js update\n - Component PRs: test visually with `npm run dev`\n\n## Don't\n- Do NOT mention pnpm — this project uses npm\n- Do NOT include SDK, OAuth, Redis, or application-specific content\n- Do NOT copy the \"Updating the Vendor SDK Package\" section from the scaffold\n- Do NOT invent Markdoc tags that do not exist in the markdoc/tags/ directory — only document callout, card-link, columns/column, and figure\n- Keep it under 250 lines","acceptance_criteria":"1. DEVELOPMENT.md exists at /Users/david/Projects/gainforest/documentation/DEVELOPMENT.md\n2. Contains all 6 sections: local dev workflow, adding pages, markdoc custom tags, project architecture, troubleshooting, contributing\n3. First-time setup instructions work: cd documentation/documentation \u0026\u0026 npm install \u0026\u0026 npm run dev\n4. Markdoc tags documented match exactly what exists in documentation/markdoc/tags/: callout, card-link, columns/column, figure (no extras, no missing)\n5. Navigation.js path is correctly referenced as documentation/lib/navigation.js\n6. References npm (not pnpm) throughout\n7. Frontmatter template shows title (required) and description (optional)\n8. File is under 250 lines\n9. No SDK, OAuth, Redis, or application-specific content","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-20T18:13:19.095143+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:13:19.095143+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-jss.2","depends_on_id":"docs-jss","type":"parent-child","created_at":"2026-02-20T18:13:19.096301+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-jss","title":"Epic: Add project-level README.md and DEVELOPMENT.md","description":"The documentation project lacks the standard project-level README.md and DEVELOPMENT.md files that our other repos (like hypercerts-scaffold-atproto) have. This epic adds both files following the same structure and style: comprehensive README with quick start, prerequisites, project structure, architecture; and DEVELOPMENT.md with local dev workflow, content authoring guide, Markdoc conventions, contributing, and troubleshooting. Success: a new contributor can clone the repo, run the docs site locally, and add a new page — all by reading README + DEVELOPMENT only.","status":"closed","priority":2,"issue_type":"epic","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","created_at":"2026-02-20T18:12:19.646036+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:14:51.247295+08:00","closed_at":"2026-02-20T18:14:51.247299+08:00","labels":["scope:medium"]} +{"id":"docs-jss.1","title":"Create README.md at project root","description":"## Files\n- README.md (create)\n\n## What to do\nCreate a comprehensive README.md at the repo root following the structure and style of hypercerts-scaffold-atproto/README.md. The file must include these sections in order:\n\n1. **Title \u0026 description** — \"Hypercerts Documentation\" heading. One paragraph: this is the official documentation site for the Hypercerts protocol, built with Next.js and Markdoc, deployed on Vercel.\n\n2. **Prerequisites** — Node.js 20+, npm (not pnpm — the project uses npm per vercel.json and package-lock.json).\n\n3. **Quick Start** — Clone, cd documentation/documentation, npm install, npm run dev. Note the nested directory structure (the actual Next.js app lives in documentation/documentation/).\n\n4. **Project Structure** — ASCII tree showing:\n```\n├── documentation/ # Next.js documentation site\n│ ├── components/ # React components (Layout, Sidebar, CodeBlock, etc.)\n│ ├── lib/ # Navigation config and helpers\n│ ├── markdoc/ # Markdoc tag and node definitions\n│ │ ├── nodes/ # Custom node renderers (fence, heading)\n│ │ └── tags/ # Custom tags (callout, card-link, columns, figure)\n│ ├── pages/ # Documentation content (.md files)\n│ │ ├── architecture/\n│ │ ├── core-concepts/\n│ │ ├── ecosystem/\n│ │ ├── getting-started/\n│ │ ├── lexicons/\n│ │ ├── reference/\n│ │ └── tools/\n│ ├── public/ # Static assets\n│ └── styles/ # CSS\n├── heartbeads-agents/ # (reserved)\n├── AGENTS.md # Agent workflow instructions\n└── .beads/ # Issue tracking\n```\n\n5. **Content Sections** — Table listing the 7 doc sections (Get Started, Core Concepts, Tools, Architecture, Reference/Lexicons, Ecosystem \u0026 Vision) with one-line descriptions, matching the style of the scaffold README tables.\n\n6. **Deployment** — State that the site is deployed on Vercel. The build command is `next build --webpack`, install command is `npm install`. Static export via `output: \"export\"` in next.config.js.\n\n7. **Learn More** — Links to: Hypercerts website (https://hypercerts.org), ATProto docs (https://atproto.com/docs), Markdoc docs (https://markdoc.dev), Next.js docs (https://nextjs.org/docs), DEVELOPMENT.md for contributor guide.\n\n## Don't\n- Do NOT mention pnpm — this project uses npm\n- Do NOT include any authentication, OAuth, or SDK content (this is a docs site, not an application)\n- Do NOT copy scaffold-specific sections (environment variables, Redis, JWK keys, etc.)\n- Do NOT add a License section (there is none currently)\n- Keep it under 150 lines","acceptance_criteria":"1. README.md exists at /Users/david/Projects/gainforest/documentation/README.md\n2. Contains all 7 sections listed in spec: title, prerequisites, quick start, project structure, content sections, deployment, learn more\n3. Quick Start instructions work: cd documentation/documentation \u0026\u0026 npm install \u0026\u0026 npm run dev starts the dev server\n4. References npm (not pnpm) throughout\n5. Project structure ASCII tree accurately reflects actual directory layout\n6. No scaffold-specific content (no Redis, OAuth, JWK, SDK references)\n7. File is under 150 lines\n8. All links in Learn More section are valid URLs","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-20T18:12:47.807873+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:14:51.095793+08:00","closed_at":"2026-02-20T18:14:51.095815+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-jss.1","depends_on_id":"docs-jss","type":"parent-child","created_at":"2026-02-20T18:12:47.809207+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-jss.2","title":"Create DEVELOPMENT.md at project root","description":"## Files\n- DEVELOPMENT.md (create)\n\n## What to do\nCreate a comprehensive DEVELOPMENT.md at the repo root following the structure and style of hypercerts-scaffold-atproto/DEVELOPMENT.md. The file must include these sections in order:\n\n1. **Local Development Workflow** heading, then:\n - **Prerequisites** — Node.js 20+, npm, Git\n - **First-time Setup** — Step-by-step: clone, cd documentation/documentation, npm install, npm run dev, open http://localhost:3000. Note the nested directory structure.\n - **Daily Development** — Just `npm run dev` in the documentation/documentation/ directory.\n - **Build for production** — `npm run build` (produces static export in `out/` directory).\n\n2. **Adding Documentation Pages** — This is the content authoring guide:\n - Explain that pages are Markdoc files (.md) in `documentation/pages/`\n - File location determines URL path (e.g., `pages/getting-started/quickstart.md` → `/getting-started/quickstart`)\n - Every page needs YAML frontmatter with `title` (required) and `description` (optional)\n - Show a template:\n ```markdown\n ---\n title: Page Title\n description: One-line description.\n ---\n\n # Page Title\n\n Content goes here.\n ```\n - After creating a page, add it to the navigation in `documentation/lib/navigation.js`\n - Explain navigation.js structure briefly: top-level items have `title` + `path`, sections have `section` + `children` array, nesting is supported\n\n3. **Markdoc Custom Tags** — List available custom tags with usage examples:\n - `{% callout type=\"note|warning|caution\" %}...{% /callout %}` — callout boxes\n - `{% card-link title=\"...\" href=\"...\" %}...{% /card-link %}` — linked cards\n - `{% columns %}{% column %}...{% /column %}{% column %}...{% /column %}{% /columns %}` — multi-column layout\n - `{% figure src=\"...\" alt=\"...\" caption=\"...\" /%}` — images with captions\n\n4. **Project Architecture** — Brief explanation:\n - Next.js with Markdoc plugin for static site generation\n - `output: \"export\"` produces fully static HTML (no server needed)\n - `pageExtensions: [\"md\", \"mdoc\", \"js\", \"jsx\", \"ts\", \"tsx\"]` — Markdoc files are treated as pages\n - Components in `components/` provide the layout shell (Layout.js), sidebar navigation (Sidebar.js), syntax highlighting (CodeBlock.js), breadcrumbs, etc.\n\n5. **Troubleshooting** — Common issues:\n - \"Module not found\" → run `npm install`\n - Page not appearing in sidebar → check navigation.js\n - Markdoc syntax errors → check tag matching ({% tag %}...{% /tag %})\n - Build fails → ensure Node.js 20+\n\n6. **Contributing** — Follow the same structure as the scaffold:\n - Fork, branch, make changes, test with `npm run build`, open PR\n - Content PRs: new/updated .md files + navigation.js update\n - Component PRs: test visually with `npm run dev`\n\n## Don't\n- Do NOT mention pnpm — this project uses npm\n- Do NOT include SDK, OAuth, Redis, or application-specific content\n- Do NOT copy the \"Updating the Vendor SDK Package\" section from the scaffold\n- Do NOT invent Markdoc tags that do not exist in the markdoc/tags/ directory — only document callout, card-link, columns/column, and figure\n- Keep it under 250 lines","acceptance_criteria":"1. DEVELOPMENT.md exists at /Users/david/Projects/gainforest/documentation/DEVELOPMENT.md\n2. Contains all 6 sections: local dev workflow, adding pages, markdoc custom tags, project architecture, troubleshooting, contributing\n3. First-time setup instructions work: cd documentation/documentation \u0026\u0026 npm install \u0026\u0026 npm run dev\n4. Markdoc tags documented match exactly what exists in documentation/markdoc/tags/: callout, card-link, columns/column, figure (no extras, no missing)\n5. Navigation.js path is correctly referenced as documentation/lib/navigation.js\n6. References npm (not pnpm) throughout\n7. Frontmatter template shows title (required) and description (optional)\n8. File is under 250 lines\n9. No SDK, OAuth, Redis, or application-specific content","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-20T18:13:19.095143+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:14:51.173268+08:00","closed_at":"2026-02-20T18:14:51.173274+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-jss.2","depends_on_id":"docs-jss","type":"parent-child","created_at":"2026-02-20T18:13:19.096301+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-l7r","title":"Epic: Ecosystem, Community \u0026 Reference Materials","status":"closed","priority":2,"issue_type":"epic","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T20:47:56.489643+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-15T01:08:20.711096+13:00","closed_at":"2026-02-15T01:08:20.711096+13:00","close_reason":"All children complete: l7r.1 (glossary + FAQ), l7r.2 (building on hypercerts)"} {"id":"docs-l7r.1","title":"Write 'Glossary' and 'FAQ' reference pages","description":"## Context\n\nDocumentation site for the Hypercerts Protocol, built with Next.js 16 + Markdoc. Site lives in `documentation/`. Pages are `.md` files in `documentation/pages/`. Nav in `documentation/lib/navigation.js`. Markdoc tags: `{% callout %}`, `{% columns %}`, `{% column %}`, `{% figure %}`, `{% card-link %}`.\n\nStripe has inline glossary definitions throughout and extensive support articles. Hypercerts uses many domain-specific terms (DID, PDS, lexicon, work scope, strong reference, etc.) but never defines them in one place. This task creates two pages.\n\n## Files\n- documentation/pages/reference/glossary.md (create)\n- documentation/pages/reference/faq.md (create)\n- documentation/lib/navigation.js (modify — add entries under Reference section)\n\n## What to do\n\n### 1. Create the Glossary page\n\nCreate `documentation/pages/reference/glossary.md` (80–120 lines of Markdoc):\n\n**Frontmatter:**\n```\n---\ntitle: Glossary\ndescription: Key terms and definitions used in the Hypercerts Protocol.\n---\n```\n\nDefine these terms (alphabetical order), each as `#### Term` followed by 1-3 sentence definition:\n\n- **Activity Claim** — The central record in the hypercerts data model. Describes who did what, when, and where. Lexicon: `org.hypercerts.claim.activity`.\n- **AT Protocol (ATProto)** — A decentralized social data protocol. The data layer for Hypercerts. Provides portable identity, shared schemas, and federation.\n- **CID** — Content Identifier. A cryptographic hash of a record's content, used in strong references to ensure tamper-evidence.\n- **Collection** — A group of hypercerts with a shared property, where each claim has a weight. Lexicon: `org.hypercerts.claim.collection`.\n- **Contribution** — A record describing a specific contributor's role in an activity claim. Lexicon: `org.hypercerts.claim.contribution`.\n- **DID (Decentralized Identifier)** — A persistent, cryptographically verifiable identifier for a person or organization. Format: `did:plc:...` or `did:web:...`.\n- **Evaluation** — A third-party assessment of a hypercert or other claim. Created on the evaluator's own PDS. Lexicon: `org.hypercerts.claim.evaluation`.\n- **Evidence** — A piece of supporting documentation attached to a hypercert. Can be a URI or uploaded blob. Lexicon: `org.hypercerts.claim.evidence`.\n- **Hypercert** — A structured digital record of a contribution: who did what, when, where, and with what evidence. The core primitive of the protocol.\n- **Indexer (App View)** — A service that reads from relays and builds queryable views of hypercert data across many PDS instances.\n- **Lexicon** — An ATProto schema definition that specifies the structure of a record type. Like a form template with required and optional fields.\n- **Measurement** — A quantitative observation attached to a claim. Lexicon: `org.hypercerts.claim.measurement`.\n- **PDS (Personal Data Server)** — A server that stores a user's ATProto data. Users can self-host or use a provider.\n- **Relay** — An ATProto service that aggregates data from many PDS instances and streams it to indexers.\n- **Rights** — A record describing what rights a holder has to a hypercert (display, transfer, etc.). Lexicon: `org.hypercerts.claim.rights`.\n- **SDS (Shared Data Server)** — Like a PDS but for organizations. Multiple users can write to the same repository.\n- **Strong Reference** — An ATProto reference that includes both the AT URI and CID of the target record, ensuring the reference is tamper-evident.\n- **Work Scope** — The \"what\" dimension of a hypercert, defined using logical operators (allOf, anyOf, noneOf) to precisely bound the work being claimed.\n- **XRPC** — The RPC protocol used by ATProto for client-server communication.\n\n### 2. Create the FAQ page\n\nCreate `documentation/pages/reference/faq.md` (80–120 lines of Markdoc):\n\n**Frontmatter:**\n```\n---\ntitle: Frequently Asked Questions\ndescription: Common questions about the Hypercerts Protocol.\n---\n```\n\nAnswer these questions (use `##` for each question, 2-4 sentences per answer):\n\n1. **What is a hypercert?** — A structured digital record of a contribution. It captures who did what, when, where, and with what evidence.\n2. **How is this different from the previous (EVM-based) Hypercerts?** — The new protocol is built on AT Protocol instead of purely on-chain. This gives data portability, richer schemas, and lower costs, while still using blockchain for ownership and funding.\n3. **Do I need a blockchain wallet?** — Not to create or evaluate hypercerts. You need an ATProto account (DID). A wallet is only needed if you want to tokenize or fund hypercerts on-chain.\n4. **Is my data public?** — Yes. All ATProto records are public by default. Do not store sensitive personal information in hypercert records.\n5. **Can I delete a hypercert?** — You can delete records from your PDS. However, cached copies may persist in indexers and relays.\n6. **Who can evaluate my hypercert?** — Anyone with an ATProto account. Evaluations are separate records on the evaluator's PDS, linked via strong references.\n7. **How do I fund a hypercert?** — Funding happens on-chain through tokenized ownership. The specific mechanisms depend on the platform you use.\n8. **Can I use my Bluesky account?** — Yes. Bluesky accounts are ATProto accounts. Your existing DID works with Hypercerts.\n9. **What chains are supported?** — The protocol is chain-agnostic for the ownership layer. Specific chain support depends on the implementation.\n10. **How do I get help?** — Link to GitHub repository, community channels (use placeholder URLs with a callout).\n\n### 3. Add to navigation\n\nAdd under the Reference section in `documentation/lib/navigation.js`:\n```javascript\n{ title: 'Glossary', path: '/reference/glossary' },\n{ title: 'FAQ', path: '/reference/faq' },\n```\nIf the Reference section does not yet exist, create it after Architecture.\n\n## Test\n```\ncd documentation \u0026\u0026 npx next build 2\u003e\u00261 | tail -5\n```\nMust exit 0.\n\n## Dont\n- Do NOT add images or new components.\n- Do NOT modify existing pages other than navigation.js.\n- Do NOT use HTML tags.\n- Do NOT invent features or capabilities not described in the existing documentation.","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T20:54:01.702733+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-15T01:06:09.77014+13:00","closed_at":"2026-02-15T01:06:09.77014+13:00","close_reason":"Created Glossary and FAQ reference pages with proper navigation","dependencies":[{"issue_id":"docs-l7r.1","depends_on_id":"docs-l7r","type":"parent-child","created_at":"2026-02-14T20:54:01.704171+13:00","created_by":"Sharfy Adamantine"}],"comments":[{"id":10,"issue_id":"docs-l7r.1","author":"Sharfy Adamantine","text":"NAV UPDATE: Add under 'Reference' section. Full nav order: Get Started → Core Concepts → Architecture → Lexicons → Tutorials → Reference.","created_at":"2026-02-14T11:25:02Z"},{"id":11,"issue_id":"docs-l7r.1","author":"Sharfy Adamantine","text":"DESIGN LANGUAGE: Follow Stripe docs (docs.stripe.com) patterns — concise definitions, scannable. No preamble, no link dumps. BUILD COMMAND FIX: Use 'cd documentation \u0026\u0026 npx next build --webpack 2\u003e\u00261 | tail -5' (must include --webpack flag). NAV PLACEMENT: Add under Reference section AFTER 'Tutorials'.","created_at":"2026-02-14T11:58:22Z"}]} {"id":"docs-l7r.2","title":"Write 'Building on Hypercerts' ecosystem guide page","description":"## Context\n\nDocumentation site for the Hypercerts Protocol, built with Next.js 16 + Markdoc. Site lives in `documentation/`. Pages are `.md` files in `documentation/pages/`. Nav in `documentation/lib/navigation.js`. Markdoc tags: `{% callout %}`, `{% columns %}`, `{% column %}`, `{% figure %}`, `{% card-link %}`.\n\nStripe's equivalent: \"Stripe Apps\" and \"Partners\" pages — guides for third parties who want to build on the platform. The hypercerts \"Why\" page mentions that the protocol is designed for many platforms to build on, but there is no guide for platform builders.\n\n## Files\n- documentation/pages/reference/building-on-hypercerts.md (create)\n- documentation/lib/navigation.js (modify — add entry under Reference section)\n\n## What to do\n\n### 1. Create the page\n\nCreate `documentation/pages/reference/building-on-hypercerts.md` (100–150 lines of Markdoc):\n\n**Frontmatter:**\n```\n---\ntitle: Building on Hypercerts\ndescription: A guide for platforms and tools that want to integrate the Hypercerts Protocol.\n---\n```\n\n**Sections:**\n\n1. **Who This Is For** — Platform builders, funding tool developers, evaluation services, dashboards, and anyone building applications that read or write hypercert data.\n\n2. **What You Can Build** — Categories of applications:\n - **Funding Platforms**: Crowdfunding, retroactive funding, milestone-based payouts using tokenized hypercerts\n - **Evaluation Tools**: Services that help domain experts create structured evaluations\n - **Dashboards \u0026 Explorers**: Interfaces that aggregate and display hypercerts across the ecosystem\n - **Impact Portfolios**: Tools that let funders track their portfolio of funded contributions\n - **Automated Agents**: AI systems that create measurements, flag inconsistencies, or assist evaluators\n\n3. **Integration Patterns** — How to integrate:\n - **Read-only**: Query an indexer to display hypercerts (simplest). No PDS needed.\n - **Write via user PDS**: Your app authenticates users via OAuth and writes records to their PDS on their behalf.\n - **Write via platform SDS**: Your platform runs its own Shared Data Server and creates records under its own DID.\n - For each pattern, provide 3-4 sentences explaining when to use it and a brief code sketch.\n\n4. **Running an Indexer** — Brief overview:\n - Subscribe to the relay firehose for hypercert lexicon records\n - Build a queryable database (PostgreSQL, etc.)\n - Expose an API for your application\n - Note: link to ATProto docs for relay subscription details\n\n5. **Interoperability Principles** — What makes the ecosystem work:\n - Use standard lexicons — do not create custom record types for data that fits existing schemas\n - Use strong references — always include CID for tamper-evidence\n - Respect data ownership — records belong to the DID that created them\n - Build for federation — do not assume all data lives on one PDS\n\n6. **Contributing to the Protocol** — How to propose changes:\n - Lexicon evolution process (propose → discuss → implement)\n - Link to GitHub repository (placeholder URL with callout)\n - How to contribute to the SDK\n\n### 2. Add to navigation\n\nAdd under the Reference section in `documentation/lib/navigation.js`:\n```javascript\n{ title: 'Building on Hypercerts', path: '/reference/building-on-hypercerts' },\n```\n\n## Test\n```\ncd documentation \u0026\u0026 npx next build 2\u003e\u00261 | tail -5\n```\nMust exit 0.\n\n## Dont\n- Do NOT add images or new components.\n- Do NOT modify existing pages other than navigation.js.\n- Do NOT use HTML tags.\n- Do NOT invent specific indexer APIs or relay endpoints.","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T20:54:24.391792+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-15T01:05:12.774851+13:00","closed_at":"2026-02-15T01:05:12.774851+13:00","close_reason":"Created Building on Hypercerts guide page with integration patterns, interoperability principles, and contribution guidelines. Build passes.","dependencies":[{"issue_id":"docs-l7r.2","depends_on_id":"docs-l7r","type":"parent-child","created_at":"2026-02-14T20:54:24.393036+13:00","created_by":"Sharfy Adamantine"}],"comments":[{"id":12,"issue_id":"docs-l7r.2","author":"Sharfy Adamantine","text":"NAV UPDATE: Add under 'Reference' section. Full nav order: Get Started → Core Concepts → Architecture → Lexicons → Tutorials → Reference.","created_at":"2026-02-14T11:25:03Z"},{"id":13,"issue_id":"docs-l7r.2","author":"Sharfy Adamantine","text":"DESIGN LANGUAGE: Follow Stripe docs (docs.stripe.com) patterns — one-sentence opener, capability bullet list, code-first, short paragraphs, no preamble, no link dumps. BUILD COMMAND FIX: Use 'cd documentation \u0026\u0026 npx next build --webpack 2\u003e\u00261 | tail -5' (must include --webpack flag). NAV PLACEMENT: Add under Reference section AFTER 'Tutorials'.","created_at":"2026-02-14T11:58:23Z"}]} From 42e842a6df49926fea8a12bd77a0c91ca822e1dc Mon Sep 17 00:00:00 2001 From: daviddao Date: Fri, 20 Feb 2026 18:22:44 +0800 Subject: [PATCH 3/7] beads: claim docs-1ho.1 --- .beads/issues.jsonl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 1e9fa13..2a8faea 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -4,9 +4,9 @@ {"id":"docs-150.3","title":"Breadcrumbs: lighter separator color, wider spacing","description":"## Files\n- documentation/components/Breadcrumbs.js (modify)\n\n## What to do\nUpdate the breadcrumb separator color and spacing to match Stripe. Currently the separator uses a dark gray; Stripe uses a lighter gray with more spacing.\n\nRead the current Breadcrumbs.js file first. Find the separator span element and update:\n1. The separator character should remain \"/\" \n2. No changes needed in the JS — the color/spacing changes are CSS-only\n\nActually, this task requires NO JS changes. The separator styling is in globals.css. Cancel this task — the CSS mega-task will handle it.\n\n## Test\nN/A — this task should be cancelled\n\n## Dont\nN/A","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:24:15.360221+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:24:21.845024+13:00","closed_at":"2026-02-14T22:24:21.845027+13:00","dependencies":[{"issue_id":"docs-150.3","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:24:15.361244+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-150.4","title":"Mega CSS: all 25 Stripe parity fixes in globals.css","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nApply ALL of the following CSS changes to globals.css. Each change is numbered and references the current line. Read the file first to confirm line numbers, then apply all changes.\n\n### Design Token Changes (in :root block, lines 72-136)\n\n1. **Unify heading colors** — Change line 87 `--color-text-heading: #353a44` to `--color-text-heading: #1a1b25` and line 88 `--color-text-title: #21252c` to `--color-text-title: #1a1b25`\n\n2. **Content max-width** — Change line 110 `--content-max-width: 800px` to `--content-max-width: 880px`\n\n3. **TOC width** — Change line 109 `--toc-width: 200px` to `--toc-width: 250px`\n\n### Add responsive sidebar width (after the :root closing brace, ~line 136)\n\n4. **Sidebar responsive** — Add after the `:root` block:\n```css\n@media (min-width: 1400px) {\n :root {\n --sidebar-width: 280px;\n }\n}\n```\n\n### Header Changes (lines 175-221)\n\n5. **Header background** — Change line 181 from `background: rgba(255, 255, 255, 0.95)` to `background: #f6f8fa`. Remove lines 182-183 (`backdrop-filter` and `-webkit-backdrop-filter`).\n\n6. **Logo font-size** — Change line 196 `font-size: 15px` to `font-size: 16px`\n\n### Breadcrumb Changes (lines 223-268)\n\n7. **Breadcrumb font-size** — Change line 235 `font-size: 13px` to `font-size: 14px`\n\n8. **Breadcrumb separator** — Change line 245 `margin: 0 6px` to `margin: 0 8px`. Change line 246 `color: var(--color-text-secondary)` to `color: #a3acba`\n\n### Sidebar Changes (lines 275-439)\n\n9. **Sidebar content padding** — Change line 304 `padding: var(--space-6) 0` to `padding: var(--space-3) 0`\n\n10. **Sidebar section spacing** — Change line 350 `margin-top: var(--space-5)` to `margin-top: var(--space-4)` and line 351 `padding-top: var(--space-5)` to `padding-top: var(--space-4)`\n\n11. **Sidebar section header** — Change the `.sidebar-section-header` rule (lines 362-369):\n```css\n.sidebar-section-header {\n font-size: 12px;\n font-weight: 600;\n text-transform: uppercase;\n letter-spacing: 0.05em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-4);\n margin-bottom: var(--space-2);\n}\n```\n\n12. **Sidebar link density** — In `.sidebar-link` (lines 384-395), change `padding: 6px var(--space-3)` to `padding: 4px var(--space-2)` and change `border-radius: var(--radius-md)` to `border-radius: var(--radius-sm)`\n\n13. **Remove old sidebar-nav-link-row and sidebar-expand-btn rules** — Delete the `.sidebar-nav-link-row` rule (lines 379-382) and the `.sidebar-expand-btn` rules (lines 420-435). These are no longer used since the chevron is now inline.\n\n14. **Add sidebar-chevron styling** — Add after the `.sidebar-link` rules:\n```css\n.sidebar-chevron {\n flex-shrink: 0;\n margin-right: 4px;\n color: var(--color-text-secondary);\n}\n```\n\n15. **Add sidebar-link-toggle** — Add:\n```css\n.sidebar-link-toggle {\n cursor: pointer;\n}\n```\n\n16. **Sidebar link needs flex for inline chevron** — Add `display: flex; align-items: center;` to `.sidebar-link` (it currently has `display: block`). Change `display: block` to `display: flex` and add `align-items: center;`\n\n17. **Sidebar active link** — Change `.sidebar-link-active` (lines 403-407):\n```css\n.sidebar-link-active {\n color: var(--color-link);\n font-weight: 500;\n background: none;\n border-left: 2px solid var(--color-link);\n margin-left: -2px;\n}\n```\n\n18. **Sidebar parent-of-active** — Change `.sidebar-link-parent-active` (lines 415-418):\n```css\n.sidebar-link-parent-active {\n font-weight: 500;\n color: var(--color-text-primary);\n}\n```\n\n### Content Area Changes (lines 441-451)\n\n19. **Content padding** — Change line 446 `padding: var(--space-10) var(--space-12)` to `padding: var(--space-8) var(--space-10)` (32px top, 40px sides)\n\n### TOC Changes (lines 453-502)\n\n20. **TOC link font-size** — Change line 484 `font-size: 13px` to `font-size: 14px`\n\n21. **TOC link spacing** — Change line 483 `padding: var(--space-1) 0` to `padding: var(--space-2) 0`\n\n22. **TOC title margin** — Change line 474 `margin-bottom: var(--space-2)` to `margin-bottom: var(--space-4)`\n\n23. **Add TOC H3 indentation** — Add after the `.toc-link-active` rule:\n```css\n.toc-link-h3 {\n padding-left: 22px;\n font-size: 13px;\n}\n```\n\n24. **TOC responsive breakpoint** — Change line 878 `@media (max-width: 1100px)` to `@media (max-width: 1200px)`\n\n### Typography Changes (lines 556-705)\n\n25. **H1** — Remove `letter-spacing: -0.02em` from `.layout-content h1` (line 564)\n\n26. **H2** — Change `.layout-content h2` (lines 567-574): `font-size: 24px`, `line-height: 32px` (was 20px / 28px)\n\n27. **H3** — Change `.layout-content h3` (lines 576-583): `font-size: 16px`, `font-weight: 700` (was 18px / 600)\n\n28. **Paragraph spacing** — Change line 633 `margin-bottom: var(--space-4)` to `margin-bottom: var(--space-3)` (12px)\n\n29. **Bold text** — Change line 598 `font-weight: 600` to `font-weight: 700`\n\n30. **Inline code border** — In the inline code rule (lines 689-696), add `border: 1px solid var(--color-border)` and change `padding: 2px 6px` to `padding: 1px 4px`\n\n31. **Code blocks dark theme** — Change `.layout-content pre` (lines 671-681):\n```css\n.layout-content pre {\n background: #0a2540;\n padding: var(--space-4);\n border-radius: var(--radius-sm);\n overflow-x: auto;\n margin-bottom: var(--space-4);\n font-family: var(--font-mono);\n font-size: 13px;\n line-height: 19px;\n color: #f5fbff;\n}\n```\n\n32. **Code block scrollbar** — Update the code block scrollbar thumb colors (lines 47-54) to work on dark background: change `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)` and `rgba(0, 0, 0, 0.2)` to `rgba(255, 255, 255, 0.25)`. Also update the Firefox scrollbar-color on line 70 from `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)`.\n\n33. **Blockquote** — Change `.layout-content blockquote` (lines 733-738): `border-left: 1px solid #c0c8d2` (was 4px solid var(--color-border)), `padding: 5px 0 5px 10px` (was 0 16px), add `font-size: 14px; line-height: 20px`\n\n34. **Table headers** — In `.layout-content th` (lines 714-720), add `text-transform: uppercase; font-size: 13px; letter-spacing: 0.03em`\n\n35. **Scrollbar gutter** — Add `scrollbar-gutter: stable;` to `.sidebar-content` (around line 303)\n\n### Link styling\n\n36. **Content links** — Change `.layout-content a` (lines 657-662): remove `border-bottom: 1px solid transparent` and add `text-decoration: underline; text-underline-offset: 2px; text-decoration-color: rgba(5, 112, 222, 0.4)`. Change `.layout-content a:hover` (lines 664-668): remove `border-bottom-color` line, change to `text-decoration-color: var(--color-link-hover)`\n\n## Test\n```bash\ncd documentation \u0026\u0026 node -e \"\nconst fs = require(\\\"fs\\\");\nconst css = fs.readFileSync(\\\"styles/globals.css\\\", \\\"utf8\\\");\nconst checks = [\n [css.includes(\\\"--color-text-heading: #1a1b25\\\"), \\\"heading color unified\\\"],\n [css.includes(\\\"--color-text-title: #1a1b25\\\"), \\\"title color unified\\\"],\n [css.includes(\\\"--content-max-width: 880px\\\"), \\\"content max-width 880\\\"],\n [css.includes(\\\"--toc-width: 250px\\\"), \\\"toc width 250\\\"],\n [css.includes(\\\"min-width: 1400px\\\"), \\\"responsive sidebar\\\"],\n [css.includes(\\\"background: #f6f8fa\\\") || css.includes(\\\"background:#f6f8fa\\\"), \\\"header solid bg\\\"],\n [css.includes(\\\"background: #0a2540\\\"), \\\"dark code blocks\\\"],\n [css.includes(\\\"color: #f5fbff\\\"), \\\"light code text\\\"],\n [css.includes(\\\"font-size: 13px\\\") \u0026\u0026 css.includes(\\\"line-height: 19px\\\"), \\\"code block sizing\\\"],\n [css.includes(\\\"toc-link-h3\\\"), \\\"toc h3 class\\\"],\n [css.includes(\\\"sidebar-chevron\\\"), \\\"sidebar chevron class\\\"],\n [css.includes(\\\"font-weight: 500\\\") \u0026\u0026 css.includes(\\\"sidebar-link-active\\\"), \\\"active link weight 500\\\"],\n [css.includes(\\\"border-left: 2px solid var(--color-link)\\\"), \\\"active left border\\\"],\n [css.includes(\\\"text-underline-offset\\\"), \\\"link underline style\\\"],\n [css.includes(\\\"scrollbar-gutter: stable\\\"), \\\"scrollbar gutter\\\"],\n [css.includes(\\\"max-width: 1200px\\\"), \\\"toc breakpoint 1200\\\"],\n [css.match(/\\\\.layout-content h2[^}]*font-size: 24px/s), \\\"h2 24px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-size: 16px/s), \\\"h3 16px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-weight: 700/s), \\\"h3 weight 700\\\"],\n];\nlet pass = true;\nfor (const [ok, name] of checks) {\n if (!ok) { console.error(\\\"FAIL: \\\" + name); pass = false; }\n else { console.log(\\\"PASS: \\\" + name); }\n}\nif (!pass) process.exit(1);\nconsole.log(\\\"\\\\nAll CSS checks passed.\\\");\n\"\n```\n\n## Dont\n- Do not modify any component JS files\n- Do not change the mobile responsive rules (keep mobile padding as-is)\n- Do not remove any CSS rules that are still referenced by components (check before deleting)\n- Do not change the design token variable names, only their values","status":"closed","priority":1,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:25:14.346526+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:31:23.234686+13:00","closed_at":"2026-02-14T22:31:23.234686+13:00","close_reason":"2fda6b5 Applied all 36 CSS changes for Stripe design parity: unified heading colors, updated layout dimensions, improved sidebar/TOC styling, dark code blocks, enhanced typography, and responsive breakpoints","dependencies":[{"issue_id":"docs-150.4","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:25:14.348237+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-1ho","title":"Epic: Adopt scaffold visual design language for docs site","description":"Migrate the documentation site's visual design (fonts, colors, radii, typography, header) to match the hypercerts-scaffold-atproto design language. The scaffold uses Syne for display/headings, Outfit for body text, Geist Mono for code, an OKLCH indigo-tinted neutral palette, 10px base radius, and a refined modern aesthetic. The docs site currently uses system fonts, hex colors (#0570de accent), plain CSS with 4-8px radii, and a light-grey header. This epic updates the CSS custom properties and font loading — it does NOT introduce Tailwind or shadcn. The docs site stays plain CSS. Success: the docs site visually reads as the same brand as the scaffold app.","status":"open","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-20T18:19:37.842151+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:19:37.842151+08:00","labels":["scope:medium"]} -{"id":"docs-1ho.1","title":"Load Syne, Outfit, and Geist Mono fonts","description":"## Files\n- documentation/components/Layout.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\n\n### 1. Add Google Fonts in Layout.js \u003cHead\u003e\nAdd a `\u003clink\u003e` tag inside the existing `\u003cHead\u003e` block to load Syne (400;500;600;700;800), Outfit (300;400;500;600;700), and Geist Mono (400;500) from Google Fonts.\n\nUse this exact URL:\n```\nhttps://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800\u0026family=Outfit:ital,wght@0,300;0,400;0,500;0,600;0,700\u0026family=Geist+Mono:wght@400;500\u0026display=swap\n```\n\nAdd both a `\u003clink rel=\"preconnect\"\u003e` for `fonts.googleapis.com` and `fonts.gstatic.com`, plus the stylesheet link. Place them BEFORE the existing `\u003cmeta\u003e` tags inside `\u003cHead\u003e`.\n\n### 2. Update CSS custom properties in globals.css\nReplace the existing `--font-sans` and `--font-mono` custom properties in the `:root` block:\n\n```css\n--font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n Helvetica, Arial, sans-serif;\n--font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n--font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco,\n Consolas, monospace;\n```\n\nNote: `--font-display` is a NEW custom property. Keep the system font fallbacks.\n\n### 3. Apply the display font to headings\nAdd these rules right after the existing `body { ... }` rule:\n\n```css\nh1, h2, h3, h4, h5, h6,\n.sidebar-section-header {\n font-family: var(--font-display);\n}\n```\n\nThis single rule applies Syne to all headings and sidebar section headers.\n\n## Don't\n- Do NOT remove any existing CSS rules\n- Do NOT change any font sizes, weights, or colors in this task (that is a separate task)\n- Do NOT add next/font — this project uses the Pages Router, use \u003clink\u003e tags\n- Do NOT add fonts to _app.js — they go in Layout.js \u003cHead\u003e\n- Do NOT touch any files other than Layout.js and globals.css","acceptance_criteria":"1. Visiting the docs site shows Outfit for body text (inspect body element, computed font-family starts with Outfit)\n2. All headings (h1-h6) render in Syne (inspect any h2, computed font-family starts with Syne)\n3. Code blocks render in Geist Mono (inspect a \u003ccode\u003e element, computed font-family starts with Geist Mono)\n4. Sidebar section headers render in Syne\n5. The Google Fonts link tag exists in the rendered HTML \u003chead\u003e\n6. Preconnect links exist for fonts.googleapis.com and fonts.gstatic.com\n7. globals.css defines three font custom properties: --font-sans, --font-display, --font-mono\n8. `npm run build` in documentation/documentation/ succeeds without errors","status":"open","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-20T18:19:58.309568+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:19:58.309568+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.1","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:19:58.310671+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.1","title":"Load Syne, Outfit, and Geist Mono fonts","description":"## Files\n- documentation/components/Layout.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\n\n### 1. Add Google Fonts in Layout.js \u003cHead\u003e\nAdd a `\u003clink\u003e` tag inside the existing `\u003cHead\u003e` block to load Syne (400;500;600;700;800), Outfit (300;400;500;600;700), and Geist Mono (400;500) from Google Fonts.\n\nUse this exact URL:\n```\nhttps://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800\u0026family=Outfit:ital,wght@0,300;0,400;0,500;0,600;0,700\u0026family=Geist+Mono:wght@400;500\u0026display=swap\n```\n\nAdd both a `\u003clink rel=\"preconnect\"\u003e` for `fonts.googleapis.com` and `fonts.gstatic.com`, plus the stylesheet link. Place them BEFORE the existing `\u003cmeta\u003e` tags inside `\u003cHead\u003e`.\n\n### 2. Update CSS custom properties in globals.css\nReplace the existing `--font-sans` and `--font-mono` custom properties in the `:root` block:\n\n```css\n--font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n Helvetica, Arial, sans-serif;\n--font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n--font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco,\n Consolas, monospace;\n```\n\nNote: `--font-display` is a NEW custom property. Keep the system font fallbacks.\n\n### 3. Apply the display font to headings\nAdd these rules right after the existing `body { ... }` rule:\n\n```css\nh1, h2, h3, h4, h5, h6,\n.sidebar-section-header {\n font-family: var(--font-display);\n}\n```\n\nThis single rule applies Syne to all headings and sidebar section headers.\n\n## Don't\n- Do NOT remove any existing CSS rules\n- Do NOT change any font sizes, weights, or colors in this task (that is a separate task)\n- Do NOT add next/font — this project uses the Pages Router, use \u003clink\u003e tags\n- Do NOT add fonts to _app.js — they go in Layout.js \u003cHead\u003e\n- Do NOT touch any files other than Layout.js and globals.css","acceptance_criteria":"1. Visiting the docs site shows Outfit for body text (inspect body element, computed font-family starts with Outfit)\n2. All headings (h1-h6) render in Syne (inspect any h2, computed font-family starts with Syne)\n3. Code blocks render in Geist Mono (inspect a \u003ccode\u003e element, computed font-family starts with Geist Mono)\n4. Sidebar section headers render in Syne\n5. The Google Fonts link tag exists in the rendered HTML \u003chead\u003e\n6. Preconnect links exist for fonts.googleapis.com and fonts.gstatic.com\n7. globals.css defines three font custom properties: --font-sans, --font-display, --font-mono\n8. `npm run build` in documentation/documentation/ succeeds without errors","status":"in_progress","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-20T18:19:58.309568+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:22:41.823471+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.1","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:19:58.310671+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.2","title":"Migrate color palette to OKLCH indigo-tinted neutrals","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nReplace the hex color values in the `:root` CSS custom properties with OKLCH equivalents that match the scaffold's indigo-tinted neutral palette (hue ~260). This aligns the docs site with the scaffold's visual identity.\n\n### Replace these custom properties in `:root`:\n\n**Neutrals:**\n```css\n/* OLD → NEW */\n--color-bg: #ffffff; → --color-bg: oklch(0.995 0.001 260);\n--color-bg-subtle: #f6f8fa; → --color-bg-subtle: oklch(0.96 0.005 260);\n--color-border: #ebeef1; → --color-border: oklch(0.91 0.005 260);\n--color-border-strong: #d8dee4; → --color-border-strong: oklch(0.86 0.008 260);\n--color-text-primary: #414552; → --color-text-primary: oklch(0.40 0.015 260);\n--color-text-heading: #1a1b25; → --color-text-heading: oklch(0.20 0.01 260);\n--color-text-title: #1a1b25; → --color-text-title: oklch(0.16 0.005 260);\n--color-text-secondary: #687385;→ --color-text-secondary: oklch(0.55 0.01 260);\n--color-text-sidebar: #414552; → --color-text-sidebar: oklch(0.40 0.015 260);\n```\n\n**Accent / Links — keep the blue but express in OKLCH:**\n```css\n--color-link: #0570de; → --color-link: oklch(0.50 0.18 260);\n--color-link-hover: #0055bc; → --color-link-hover: oklch(0.43 0.19 260);\n--color-accent: #0570de; → --color-accent: oklch(0.50 0.18 260);\n```\n\n**Interaction colors (misc section):**\n```css\n--hover-bg: #f6f8fa; → --hover-bg: oklch(0.96 0.005 260);\n--active-bg: #f0f4ff; → --active-bg: oklch(0.95 0.015 260);\n--focus-ring: 0 0 0 4px rgba(5, 112, 222, 0.36); → --focus-ring: 0 0 0 4px oklch(0.50 0.18 260 / 0.36);\n```\n\n**Callout colors — keep the hues but express in OKLCH:**\n```css\n--color-info: #0570de; → --color-info: oklch(0.50 0.18 260);\n--color-info-bg: #f0f7ff; → --color-info-bg: oklch(0.96 0.02 260);\n--color-warning: #c84801; → --color-warning: oklch(0.55 0.17 55);\n--color-warning-bg: #fef9f0; → --color-warning-bg: oklch(0.97 0.02 80);\n--color-danger: #df1b41; → --color-danger: oklch(0.52 0.22 25);\n--color-danger-bg: #fef0f4; → --color-danger-bg: oklch(0.97 0.02 15);\n--color-success: #228403; → --color-success: oklch(0.52 0.17 145);\n--color-success-bg: #f0fef0; → --color-success-bg: oklch(0.97 0.03 145);\n```\n\n### Also update these hardcoded colors in other selectors:\n\n1. `.layout-header` background: change `#f6f8fa` → `oklch(0.985 0.002 260)` (scaffold's background tone for the header — near-white, matching the page body but with a faint warmth)\n\n2. `.breadcrumbs-separator` color: change `#a3acba` → `oklch(0.70 0.01 260)`\n\n3. `.layout-content blockquote` border-left color: change `#c0c8d2` → `oklch(0.80 0.01 260)`\n\n### DO NOT change these hardcoded colors (they are code-block-specific and should stay):\n- `#011627` (Night Owl background)\n- `#0d2137` (code block header)\n- `#1e3a5f` (code block border)\n- `#8899aa`, `#556677`, `#aabbcc` (code block UI elements)\n- Any `rgba(255, 255, 255, ...)` scrollbar colors inside code blocks\n\n## Don't\n- Do NOT change font families, font sizes, font weights, or spacing\n- Do NOT change the code block color scheme (Night Owl)\n- Do NOT touch Layout.js or any other files\n- Do NOT add dark mode (separate concern)\n- Do NOT change the LANGUAGE_META colors in CodeBlock.js\n- Do NOT add new CSS rules — only modify existing property values","acceptance_criteria":"1. All `:root` color custom properties use oklch() syntax (no hex values remain for tokens listed above)\n2. The page background is near-white with a faint blue tint (visually similar to before but not pure white)\n3. Links are still blue and visually similar to before\n4. Callout boxes still show 4 distinct colors (blue info, orange warning, red danger, green success)\n5. Code blocks are unchanged (Night Owl dark blue background preserved)\n6. Header background is updated to oklch value\n7. Breadcrumb separator and blockquote border use oklch values\n8. `npm run build` in documentation/documentation/ succeeds without errors\n9. The site loads correctly in Chrome 111+ and Safari 15.4+ (oklch browser support baseline)","status":"open","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-20T18:20:31.538843+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:20:31.538843+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:31.54053+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:20:31.542591+08:00","created_by":"einstein.climateai.org"}]} -{"id":"docs-1ho.3","title":"Update border radii and spacing to match scaffold","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate the border radius custom properties and a few spacing values to match the scaffold's more rounded, modern aesthetic.\n\n### 1. Update radius tokens in `:root`\n```css\n/* OLD → NEW */\n--radius-sm: 4px; → --radius-sm: 6px;\n--radius-md: 6px; → --radius-md: 8px;\n--radius-lg: 8px; → --radius-lg: 10px;\n```\n\nAlso add a new token after `--radius-lg`:\n```css\n--radius-xl: 14px;\n```\n\n### 2. Update the code block border-radius\nIn `.codeblock`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\nIn the fallback rule `.layout-content pre:not(.codeblock-pre)`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\n### 3. Update card-link border-radius\nIn `.card-link`, change:\n```css\nborder-radius: var(--radius-lg);\n```\nThis already uses the token — it will automatically pick up the new 10px value. No change needed.\n\n### 4. Update pagination-link border-radius\nIn `.pagination-link`, it already uses `var(--radius-lg)` — will pick up automatically.\n\n## Don't\n- Do NOT change any font, color, or typography properties\n- Do NOT change spacing tokens (--space-*) — they are fine as-is\n- Do NOT change the code block internal padding or header styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. --radius-sm is 6px, --radius-md is 8px, --radius-lg is 10px, --radius-xl is 14px in :root\n2. Code blocks have 10px border radius (inspect .codeblock element)\n3. Card links have 10px border radius\n4. Sidebar links have 8px border radius (--radius-md)\n5. Inline code still has rounded corners (uses --radius-sm = 6px now)\n6. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:20:48.238131+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:20:48.238131+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.3","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:48.239264+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.3","title":"Update border radii and spacing to match scaffold","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate the border radius custom properties and a few spacing values to match the scaffold's more rounded, modern aesthetic.\n\n### 1. Update radius tokens in `:root`\n```css\n/* OLD → NEW */\n--radius-sm: 4px; → --radius-sm: 6px;\n--radius-md: 6px; → --radius-md: 8px;\n--radius-lg: 8px; → --radius-lg: 10px;\n```\n\nAlso add a new token after `--radius-lg`:\n```css\n--radius-xl: 14px;\n```\n\n### 2. Update the code block border-radius\nIn `.codeblock`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\nIn the fallback rule `.layout-content pre:not(.codeblock-pre)`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\n### 3. Update card-link border-radius\nIn `.card-link`, change:\n```css\nborder-radius: var(--radius-lg);\n```\nThis already uses the token — it will automatically pick up the new 10px value. No change needed.\n\n### 4. Update pagination-link border-radius\nIn `.pagination-link`, it already uses `var(--radius-lg)` — will pick up automatically.\n\n## Don't\n- Do NOT change any font, color, or typography properties\n- Do NOT change spacing tokens (--space-*) — they are fine as-is\n- Do NOT change the code block internal padding or header styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. --radius-sm is 6px, --radius-md is 8px, --radius-lg is 10px, --radius-xl is 14px in :root\n2. Code blocks have 10px border radius (inspect .codeblock element)\n3. Card links have 10px border radius\n4. Sidebar links have 8px border radius (--radius-md)\n5. Inline code still has rounded corners (uses --radius-sm = 6px now)\n6. `npm run build` succeeds without errors","status":"in_progress","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:20:48.238131+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:22:42.034305+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.3","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:48.239264+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.4","title":"Refine heading typography to match scaffold display style","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate heading styles to match the scaffold's Syne display typography conventions. The scaffold uses tighter letter-spacing and bolder heading hierarchy with Syne. These changes assume docs-1ho.1 (font loading) is already applied.\n\n### 1. Update `.layout-content h1`\nAdd `letter-spacing: -0.02em;` (tracking-tight in scaffold convention).\nKeep all other properties (font-size: 32px, font-weight: 700, etc.) unchanged.\n\n### 2. Update `.layout-content h2`\nAdd `letter-spacing: -0.01em;`.\nKeep all other properties unchanged.\n\n### 3. Update `.sidebar-section-header`\nChange from:\n```css\n.sidebar-section-header {\n font-size: 14px;\n font-weight: 600;\n text-transform: uppercase;\n color: var(--color-text-heading);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\nTo:\n```css\n.sidebar-section-header {\n font-size: 11px;\n font-weight: 700;\n text-transform: uppercase;\n letter-spacing: 0.08em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\n\nThis matches the scaffold's convention: sidebar section headers are smaller (11px), bolder (700), wider-tracked (0.08em), and use secondary color to feel like category labels rather than content headings.\n\n### 4. Update `.toc-title`\nChange `font-weight: 700` → `font-weight: 600` and add `font-family: var(--font-display);`\n\nThis gives the TOC \"On this page\" label the Syne display treatment.\n\n## Don't\n- Do NOT change font-size on h1, h2, h3, h4 (only add letter-spacing)\n- Do NOT change any colors (that is the colors task)\n- Do NOT change body text or paragraph styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. H1 has letter-spacing: -0.02em (inspect computed style)\n2. H2 has letter-spacing: -0.01em\n3. Sidebar section headers are 11px, font-weight 700, letter-spacing 0.08em, color is --color-text-secondary\n4. TOC title uses Syne (font-family: var(--font-display))\n5. No heading font sizes have changed from their current values\n6. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:21:05.00645+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:05.00645+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:05.008011+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:05.009956+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.5","title":"Add antialiased rendering and body font-weight","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nThe scaffold uses `antialiased` font rendering and Outfit at weight 400 for body text. The docs site already has `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` on body — but Outfit renders slightly differently than system fonts at the default weight. Add `font-weight: 400;` explicitly to the `body` rule to ensure consistent rendering with Outfit.\n\n### 1. In the `body { ... }` rule, add:\n```css\nfont-weight: 400;\n```\nPlace it after `font-size: 16px;`.\n\n### 2. Update the existing `body` line-height from `1.65` to `1.6`\nThe scaffold uses tighter line-height with Outfit. Change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n### 3. Update list item line-height to match\nIn `.layout-content article li`, change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n## Don't\n- Do NOT change any font-family properties\n- Do NOT change any colors\n- Do NOT change heading styles\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. Body element has font-weight: 400 in computed styles\n2. Body element has line-height: 1.6\n3. List items have line-height: 1.6\n4. Text renders with antialiased smoothing (already present, verify not removed)\n5. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-20T18:21:19.242335+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:19.242335+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:19.243605+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:19.245486+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-390","title":"Epic: Replace speculative blockchain/tokenization language with freeze-then-fund model across all docs","status":"closed","priority":1,"issue_type":"epic","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:19:57.096114+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T19:52:57.976277+13:00","closed_at":"2026-02-16T19:52:57.976277+13:00","close_reason":"Closed"} From db0ab3a07daa58be394127acf9ba39c84b1a221d Mon Sep 17 00:00:00 2001 From: daviddao Date: Fri, 20 Feb 2026 18:24:34 +0800 Subject: [PATCH 4/7] Load Syne, Outfit, and Geist Mono fonts (docs-1ho.1) --- documentation/components/Layout.js | 6 ++++++ documentation/styles/globals.css | 26 ++++++++++++++++---------- 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/documentation/components/Layout.js b/documentation/components/Layout.js index c117333..7402ceb 100644 --- a/documentation/components/Layout.js +++ b/documentation/components/Layout.js @@ -36,6 +36,12 @@ export default function Layout({ children, frontmatter }) { return ( <> + + + {pageTitle} {frontmatter?.description && ( diff --git a/documentation/styles/globals.css b/documentation/styles/globals.css index 5633681..7963434 100644 --- a/documentation/styles/globals.css +++ b/documentation/styles/globals.css @@ -72,11 +72,11 @@ /* ===== Design Tokens ===== */ :root { /* Font stacks */ - --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, - Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', - 'Segoe UI Symbol'; - --font-mono: 'Source Code Pro', SFMono-Regular, Menlo, Monaco, Consolas, - monospace; + --font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, + Helvetica, Arial, sans-serif; + --font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + --font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco, + Consolas, monospace; /* Neutrals */ --color-bg: #ffffff; @@ -126,9 +126,10 @@ --hover-bg: #f6f8fa; --active-bg: #f0f4ff; --focus-ring: 0 0 0 4px rgba(5, 112, 222, 0.36); - --radius-sm: 4px; - --radius-md: 6px; - --radius-lg: 8px; + --radius-sm: 6px; + --radius-md: 8px; + --radius-lg: 10px; + --radius-xl: 14px; /* Transitions */ --transition-fast: 150ms ease; @@ -157,6 +158,11 @@ body { font-size: 16px; } +h1, h2, h3, h4, h5, h6, +.sidebar-section-header { + font-family: var(--font-display); +} + a { color: var(--color-link); text-decoration: none; @@ -692,7 +698,7 @@ a.sidebar-link-active:hover { /* Code blocks */ .codeblock { margin-bottom: var(--space-4); - border-radius: 8px; + border-radius: var(--radius-lg); overflow: hidden; border: 1px solid #1e3a5f; } @@ -769,7 +775,7 @@ a.sidebar-link-active:hover { .layout-content pre:not(.codeblock-pre) { background: #011627; padding: var(--space-4); - border-radius: 8px; + border-radius: var(--radius-lg); overflow-x: auto; margin-bottom: var(--space-4); font-family: var(--font-mono); From 8d7ef9ee5e5d16fc6f5bdbd3189d201e9161e681 Mon Sep 17 00:00:00 2001 From: daviddao Date: Fri, 20 Feb 2026 18:24:42 +0800 Subject: [PATCH 5/7] beads: close docs-1ho.1 --- .beads/issues.jsonl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 2a8faea..8596068 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -4,7 +4,7 @@ {"id":"docs-150.3","title":"Breadcrumbs: lighter separator color, wider spacing","description":"## Files\n- documentation/components/Breadcrumbs.js (modify)\n\n## What to do\nUpdate the breadcrumb separator color and spacing to match Stripe. Currently the separator uses a dark gray; Stripe uses a lighter gray with more spacing.\n\nRead the current Breadcrumbs.js file first. Find the separator span element and update:\n1. The separator character should remain \"/\" \n2. No changes needed in the JS — the color/spacing changes are CSS-only\n\nActually, this task requires NO JS changes. The separator styling is in globals.css. Cancel this task — the CSS mega-task will handle it.\n\n## Test\nN/A — this task should be cancelled\n\n## Dont\nN/A","status":"closed","priority":2,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:24:15.360221+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:24:21.845024+13:00","closed_at":"2026-02-14T22:24:21.845027+13:00","dependencies":[{"issue_id":"docs-150.3","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:24:15.361244+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-150.4","title":"Mega CSS: all 25 Stripe parity fixes in globals.css","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nApply ALL of the following CSS changes to globals.css. Each change is numbered and references the current line. Read the file first to confirm line numbers, then apply all changes.\n\n### Design Token Changes (in :root block, lines 72-136)\n\n1. **Unify heading colors** — Change line 87 `--color-text-heading: #353a44` to `--color-text-heading: #1a1b25` and line 88 `--color-text-title: #21252c` to `--color-text-title: #1a1b25`\n\n2. **Content max-width** — Change line 110 `--content-max-width: 800px` to `--content-max-width: 880px`\n\n3. **TOC width** — Change line 109 `--toc-width: 200px` to `--toc-width: 250px`\n\n### Add responsive sidebar width (after the :root closing brace, ~line 136)\n\n4. **Sidebar responsive** — Add after the `:root` block:\n```css\n@media (min-width: 1400px) {\n :root {\n --sidebar-width: 280px;\n }\n}\n```\n\n### Header Changes (lines 175-221)\n\n5. **Header background** — Change line 181 from `background: rgba(255, 255, 255, 0.95)` to `background: #f6f8fa`. Remove lines 182-183 (`backdrop-filter` and `-webkit-backdrop-filter`).\n\n6. **Logo font-size** — Change line 196 `font-size: 15px` to `font-size: 16px`\n\n### Breadcrumb Changes (lines 223-268)\n\n7. **Breadcrumb font-size** — Change line 235 `font-size: 13px` to `font-size: 14px`\n\n8. **Breadcrumb separator** — Change line 245 `margin: 0 6px` to `margin: 0 8px`. Change line 246 `color: var(--color-text-secondary)` to `color: #a3acba`\n\n### Sidebar Changes (lines 275-439)\n\n9. **Sidebar content padding** — Change line 304 `padding: var(--space-6) 0` to `padding: var(--space-3) 0`\n\n10. **Sidebar section spacing** — Change line 350 `margin-top: var(--space-5)` to `margin-top: var(--space-4)` and line 351 `padding-top: var(--space-5)` to `padding-top: var(--space-4)`\n\n11. **Sidebar section header** — Change the `.sidebar-section-header` rule (lines 362-369):\n```css\n.sidebar-section-header {\n font-size: 12px;\n font-weight: 600;\n text-transform: uppercase;\n letter-spacing: 0.05em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-4);\n margin-bottom: var(--space-2);\n}\n```\n\n12. **Sidebar link density** — In `.sidebar-link` (lines 384-395), change `padding: 6px var(--space-3)` to `padding: 4px var(--space-2)` and change `border-radius: var(--radius-md)` to `border-radius: var(--radius-sm)`\n\n13. **Remove old sidebar-nav-link-row and sidebar-expand-btn rules** — Delete the `.sidebar-nav-link-row` rule (lines 379-382) and the `.sidebar-expand-btn` rules (lines 420-435). These are no longer used since the chevron is now inline.\n\n14. **Add sidebar-chevron styling** — Add after the `.sidebar-link` rules:\n```css\n.sidebar-chevron {\n flex-shrink: 0;\n margin-right: 4px;\n color: var(--color-text-secondary);\n}\n```\n\n15. **Add sidebar-link-toggle** — Add:\n```css\n.sidebar-link-toggle {\n cursor: pointer;\n}\n```\n\n16. **Sidebar link needs flex for inline chevron** — Add `display: flex; align-items: center;` to `.sidebar-link` (it currently has `display: block`). Change `display: block` to `display: flex` and add `align-items: center;`\n\n17. **Sidebar active link** — Change `.sidebar-link-active` (lines 403-407):\n```css\n.sidebar-link-active {\n color: var(--color-link);\n font-weight: 500;\n background: none;\n border-left: 2px solid var(--color-link);\n margin-left: -2px;\n}\n```\n\n18. **Sidebar parent-of-active** — Change `.sidebar-link-parent-active` (lines 415-418):\n```css\n.sidebar-link-parent-active {\n font-weight: 500;\n color: var(--color-text-primary);\n}\n```\n\n### Content Area Changes (lines 441-451)\n\n19. **Content padding** — Change line 446 `padding: var(--space-10) var(--space-12)` to `padding: var(--space-8) var(--space-10)` (32px top, 40px sides)\n\n### TOC Changes (lines 453-502)\n\n20. **TOC link font-size** — Change line 484 `font-size: 13px` to `font-size: 14px`\n\n21. **TOC link spacing** — Change line 483 `padding: var(--space-1) 0` to `padding: var(--space-2) 0`\n\n22. **TOC title margin** — Change line 474 `margin-bottom: var(--space-2)` to `margin-bottom: var(--space-4)`\n\n23. **Add TOC H3 indentation** — Add after the `.toc-link-active` rule:\n```css\n.toc-link-h3 {\n padding-left: 22px;\n font-size: 13px;\n}\n```\n\n24. **TOC responsive breakpoint** — Change line 878 `@media (max-width: 1100px)` to `@media (max-width: 1200px)`\n\n### Typography Changes (lines 556-705)\n\n25. **H1** — Remove `letter-spacing: -0.02em` from `.layout-content h1` (line 564)\n\n26. **H2** — Change `.layout-content h2` (lines 567-574): `font-size: 24px`, `line-height: 32px` (was 20px / 28px)\n\n27. **H3** — Change `.layout-content h3` (lines 576-583): `font-size: 16px`, `font-weight: 700` (was 18px / 600)\n\n28. **Paragraph spacing** — Change line 633 `margin-bottom: var(--space-4)` to `margin-bottom: var(--space-3)` (12px)\n\n29. **Bold text** — Change line 598 `font-weight: 600` to `font-weight: 700`\n\n30. **Inline code border** — In the inline code rule (lines 689-696), add `border: 1px solid var(--color-border)` and change `padding: 2px 6px` to `padding: 1px 4px`\n\n31. **Code blocks dark theme** — Change `.layout-content pre` (lines 671-681):\n```css\n.layout-content pre {\n background: #0a2540;\n padding: var(--space-4);\n border-radius: var(--radius-sm);\n overflow-x: auto;\n margin-bottom: var(--space-4);\n font-family: var(--font-mono);\n font-size: 13px;\n line-height: 19px;\n color: #f5fbff;\n}\n```\n\n32. **Code block scrollbar** — Update the code block scrollbar thumb colors (lines 47-54) to work on dark background: change `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)` and `rgba(0, 0, 0, 0.2)` to `rgba(255, 255, 255, 0.25)`. Also update the Firefox scrollbar-color on line 70 from `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)`.\n\n33. **Blockquote** — Change `.layout-content blockquote` (lines 733-738): `border-left: 1px solid #c0c8d2` (was 4px solid var(--color-border)), `padding: 5px 0 5px 10px` (was 0 16px), add `font-size: 14px; line-height: 20px`\n\n34. **Table headers** — In `.layout-content th` (lines 714-720), add `text-transform: uppercase; font-size: 13px; letter-spacing: 0.03em`\n\n35. **Scrollbar gutter** — Add `scrollbar-gutter: stable;` to `.sidebar-content` (around line 303)\n\n### Link styling\n\n36. **Content links** — Change `.layout-content a` (lines 657-662): remove `border-bottom: 1px solid transparent` and add `text-decoration: underline; text-underline-offset: 2px; text-decoration-color: rgba(5, 112, 222, 0.4)`. Change `.layout-content a:hover` (lines 664-668): remove `border-bottom-color` line, change to `text-decoration-color: var(--color-link-hover)`\n\n## Test\n```bash\ncd documentation \u0026\u0026 node -e \"\nconst fs = require(\\\"fs\\\");\nconst css = fs.readFileSync(\\\"styles/globals.css\\\", \\\"utf8\\\");\nconst checks = [\n [css.includes(\\\"--color-text-heading: #1a1b25\\\"), \\\"heading color unified\\\"],\n [css.includes(\\\"--color-text-title: #1a1b25\\\"), \\\"title color unified\\\"],\n [css.includes(\\\"--content-max-width: 880px\\\"), \\\"content max-width 880\\\"],\n [css.includes(\\\"--toc-width: 250px\\\"), \\\"toc width 250\\\"],\n [css.includes(\\\"min-width: 1400px\\\"), \\\"responsive sidebar\\\"],\n [css.includes(\\\"background: #f6f8fa\\\") || css.includes(\\\"background:#f6f8fa\\\"), \\\"header solid bg\\\"],\n [css.includes(\\\"background: #0a2540\\\"), \\\"dark code blocks\\\"],\n [css.includes(\\\"color: #f5fbff\\\"), \\\"light code text\\\"],\n [css.includes(\\\"font-size: 13px\\\") \u0026\u0026 css.includes(\\\"line-height: 19px\\\"), \\\"code block sizing\\\"],\n [css.includes(\\\"toc-link-h3\\\"), \\\"toc h3 class\\\"],\n [css.includes(\\\"sidebar-chevron\\\"), \\\"sidebar chevron class\\\"],\n [css.includes(\\\"font-weight: 500\\\") \u0026\u0026 css.includes(\\\"sidebar-link-active\\\"), \\\"active link weight 500\\\"],\n [css.includes(\\\"border-left: 2px solid var(--color-link)\\\"), \\\"active left border\\\"],\n [css.includes(\\\"text-underline-offset\\\"), \\\"link underline style\\\"],\n [css.includes(\\\"scrollbar-gutter: stable\\\"), \\\"scrollbar gutter\\\"],\n [css.includes(\\\"max-width: 1200px\\\"), \\\"toc breakpoint 1200\\\"],\n [css.match(/\\\\.layout-content h2[^}]*font-size: 24px/s), \\\"h2 24px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-size: 16px/s), \\\"h3 16px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-weight: 700/s), \\\"h3 weight 700\\\"],\n];\nlet pass = true;\nfor (const [ok, name] of checks) {\n if (!ok) { console.error(\\\"FAIL: \\\" + name); pass = false; }\n else { console.log(\\\"PASS: \\\" + name); }\n}\nif (!pass) process.exit(1);\nconsole.log(\\\"\\\\nAll CSS checks passed.\\\");\n\"\n```\n\n## Dont\n- Do not modify any component JS files\n- Do not change the mobile responsive rules (keep mobile padding as-is)\n- Do not remove any CSS rules that are still referenced by components (check before deleting)\n- Do not change the design token variable names, only their values","status":"closed","priority":1,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:25:14.346526+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:31:23.234686+13:00","closed_at":"2026-02-14T22:31:23.234686+13:00","close_reason":"2fda6b5 Applied all 36 CSS changes for Stripe design parity: unified heading colors, updated layout dimensions, improved sidebar/TOC styling, dark code blocks, enhanced typography, and responsive breakpoints","dependencies":[{"issue_id":"docs-150.4","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:25:14.348237+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-1ho","title":"Epic: Adopt scaffold visual design language for docs site","description":"Migrate the documentation site's visual design (fonts, colors, radii, typography, header) to match the hypercerts-scaffold-atproto design language. The scaffold uses Syne for display/headings, Outfit for body text, Geist Mono for code, an OKLCH indigo-tinted neutral palette, 10px base radius, and a refined modern aesthetic. The docs site currently uses system fonts, hex colors (#0570de accent), plain CSS with 4-8px radii, and a light-grey header. This epic updates the CSS custom properties and font loading — it does NOT introduce Tailwind or shadcn. The docs site stays plain CSS. Success: the docs site visually reads as the same brand as the scaffold app.","status":"open","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-20T18:19:37.842151+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:19:37.842151+08:00","labels":["scope:medium"]} -{"id":"docs-1ho.1","title":"Load Syne, Outfit, and Geist Mono fonts","description":"## Files\n- documentation/components/Layout.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\n\n### 1. Add Google Fonts in Layout.js \u003cHead\u003e\nAdd a `\u003clink\u003e` tag inside the existing `\u003cHead\u003e` block to load Syne (400;500;600;700;800), Outfit (300;400;500;600;700), and Geist Mono (400;500) from Google Fonts.\n\nUse this exact URL:\n```\nhttps://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800\u0026family=Outfit:ital,wght@0,300;0,400;0,500;0,600;0,700\u0026family=Geist+Mono:wght@400;500\u0026display=swap\n```\n\nAdd both a `\u003clink rel=\"preconnect\"\u003e` for `fonts.googleapis.com` and `fonts.gstatic.com`, plus the stylesheet link. Place them BEFORE the existing `\u003cmeta\u003e` tags inside `\u003cHead\u003e`.\n\n### 2. Update CSS custom properties in globals.css\nReplace the existing `--font-sans` and `--font-mono` custom properties in the `:root` block:\n\n```css\n--font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n Helvetica, Arial, sans-serif;\n--font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n--font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco,\n Consolas, monospace;\n```\n\nNote: `--font-display` is a NEW custom property. Keep the system font fallbacks.\n\n### 3. Apply the display font to headings\nAdd these rules right after the existing `body { ... }` rule:\n\n```css\nh1, h2, h3, h4, h5, h6,\n.sidebar-section-header {\n font-family: var(--font-display);\n}\n```\n\nThis single rule applies Syne to all headings and sidebar section headers.\n\n## Don't\n- Do NOT remove any existing CSS rules\n- Do NOT change any font sizes, weights, or colors in this task (that is a separate task)\n- Do NOT add next/font — this project uses the Pages Router, use \u003clink\u003e tags\n- Do NOT add fonts to _app.js — they go in Layout.js \u003cHead\u003e\n- Do NOT touch any files other than Layout.js and globals.css","acceptance_criteria":"1. Visiting the docs site shows Outfit for body text (inspect body element, computed font-family starts with Outfit)\n2. All headings (h1-h6) render in Syne (inspect any h2, computed font-family starts with Syne)\n3. Code blocks render in Geist Mono (inspect a \u003ccode\u003e element, computed font-family starts with Geist Mono)\n4. Sidebar section headers render in Syne\n5. The Google Fonts link tag exists in the rendered HTML \u003chead\u003e\n6. Preconnect links exist for fonts.googleapis.com and fonts.gstatic.com\n7. globals.css defines three font custom properties: --font-sans, --font-display, --font-mono\n8. `npm run build` in documentation/documentation/ succeeds without errors","status":"in_progress","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-20T18:19:58.309568+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:22:41.823471+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.1","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:19:58.310671+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.1","title":"Load Syne, Outfit, and Geist Mono fonts","description":"## Files\n- documentation/components/Layout.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\n\n### 1. Add Google Fonts in Layout.js \u003cHead\u003e\nAdd a `\u003clink\u003e` tag inside the existing `\u003cHead\u003e` block to load Syne (400;500;600;700;800), Outfit (300;400;500;600;700), and Geist Mono (400;500) from Google Fonts.\n\nUse this exact URL:\n```\nhttps://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800\u0026family=Outfit:ital,wght@0,300;0,400;0,500;0,600;0,700\u0026family=Geist+Mono:wght@400;500\u0026display=swap\n```\n\nAdd both a `\u003clink rel=\"preconnect\"\u003e` for `fonts.googleapis.com` and `fonts.gstatic.com`, plus the stylesheet link. Place them BEFORE the existing `\u003cmeta\u003e` tags inside `\u003cHead\u003e`.\n\n### 2. Update CSS custom properties in globals.css\nReplace the existing `--font-sans` and `--font-mono` custom properties in the `:root` block:\n\n```css\n--font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n Helvetica, Arial, sans-serif;\n--font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n--font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco,\n Consolas, monospace;\n```\n\nNote: `--font-display` is a NEW custom property. Keep the system font fallbacks.\n\n### 3. Apply the display font to headings\nAdd these rules right after the existing `body { ... }` rule:\n\n```css\nh1, h2, h3, h4, h5, h6,\n.sidebar-section-header {\n font-family: var(--font-display);\n}\n```\n\nThis single rule applies Syne to all headings and sidebar section headers.\n\n## Don't\n- Do NOT remove any existing CSS rules\n- Do NOT change any font sizes, weights, or colors in this task (that is a separate task)\n- Do NOT add next/font — this project uses the Pages Router, use \u003clink\u003e tags\n- Do NOT add fonts to _app.js — they go in Layout.js \u003cHead\u003e\n- Do NOT touch any files other than Layout.js and globals.css","acceptance_criteria":"1. Visiting the docs site shows Outfit for body text (inspect body element, computed font-family starts with Outfit)\n2. All headings (h1-h6) render in Syne (inspect any h2, computed font-family starts with Syne)\n3. Code blocks render in Geist Mono (inspect a \u003ccode\u003e element, computed font-family starts with Geist Mono)\n4. Sidebar section headers render in Syne\n5. The Google Fonts link tag exists in the rendered HTML \u003chead\u003e\n6. Preconnect links exist for fonts.googleapis.com and fonts.gstatic.com\n7. globals.css defines three font custom properties: --font-sans, --font-display, --font-mono\n8. `npm run build` in documentation/documentation/ succeeds without errors","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-20T18:19:58.309568+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:24:39.028803+08:00","closed_at":"2026-02-20T18:24:39.028803+08:00","close_reason":"db0ab3a Load Syne, Outfit, and Geist Mono fonts","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.1","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:19:58.310671+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.2","title":"Migrate color palette to OKLCH indigo-tinted neutrals","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nReplace the hex color values in the `:root` CSS custom properties with OKLCH equivalents that match the scaffold's indigo-tinted neutral palette (hue ~260). This aligns the docs site with the scaffold's visual identity.\n\n### Replace these custom properties in `:root`:\n\n**Neutrals:**\n```css\n/* OLD → NEW */\n--color-bg: #ffffff; → --color-bg: oklch(0.995 0.001 260);\n--color-bg-subtle: #f6f8fa; → --color-bg-subtle: oklch(0.96 0.005 260);\n--color-border: #ebeef1; → --color-border: oklch(0.91 0.005 260);\n--color-border-strong: #d8dee4; → --color-border-strong: oklch(0.86 0.008 260);\n--color-text-primary: #414552; → --color-text-primary: oklch(0.40 0.015 260);\n--color-text-heading: #1a1b25; → --color-text-heading: oklch(0.20 0.01 260);\n--color-text-title: #1a1b25; → --color-text-title: oklch(0.16 0.005 260);\n--color-text-secondary: #687385;→ --color-text-secondary: oklch(0.55 0.01 260);\n--color-text-sidebar: #414552; → --color-text-sidebar: oklch(0.40 0.015 260);\n```\n\n**Accent / Links — keep the blue but express in OKLCH:**\n```css\n--color-link: #0570de; → --color-link: oklch(0.50 0.18 260);\n--color-link-hover: #0055bc; → --color-link-hover: oklch(0.43 0.19 260);\n--color-accent: #0570de; → --color-accent: oklch(0.50 0.18 260);\n```\n\n**Interaction colors (misc section):**\n```css\n--hover-bg: #f6f8fa; → --hover-bg: oklch(0.96 0.005 260);\n--active-bg: #f0f4ff; → --active-bg: oklch(0.95 0.015 260);\n--focus-ring: 0 0 0 4px rgba(5, 112, 222, 0.36); → --focus-ring: 0 0 0 4px oklch(0.50 0.18 260 / 0.36);\n```\n\n**Callout colors — keep the hues but express in OKLCH:**\n```css\n--color-info: #0570de; → --color-info: oklch(0.50 0.18 260);\n--color-info-bg: #f0f7ff; → --color-info-bg: oklch(0.96 0.02 260);\n--color-warning: #c84801; → --color-warning: oklch(0.55 0.17 55);\n--color-warning-bg: #fef9f0; → --color-warning-bg: oklch(0.97 0.02 80);\n--color-danger: #df1b41; → --color-danger: oklch(0.52 0.22 25);\n--color-danger-bg: #fef0f4; → --color-danger-bg: oklch(0.97 0.02 15);\n--color-success: #228403; → --color-success: oklch(0.52 0.17 145);\n--color-success-bg: #f0fef0; → --color-success-bg: oklch(0.97 0.03 145);\n```\n\n### Also update these hardcoded colors in other selectors:\n\n1. `.layout-header` background: change `#f6f8fa` → `oklch(0.985 0.002 260)` (scaffold's background tone for the header — near-white, matching the page body but with a faint warmth)\n\n2. `.breadcrumbs-separator` color: change `#a3acba` → `oklch(0.70 0.01 260)`\n\n3. `.layout-content blockquote` border-left color: change `#c0c8d2` → `oklch(0.80 0.01 260)`\n\n### DO NOT change these hardcoded colors (they are code-block-specific and should stay):\n- `#011627` (Night Owl background)\n- `#0d2137` (code block header)\n- `#1e3a5f` (code block border)\n- `#8899aa`, `#556677`, `#aabbcc` (code block UI elements)\n- Any `rgba(255, 255, 255, ...)` scrollbar colors inside code blocks\n\n## Don't\n- Do NOT change font families, font sizes, font weights, or spacing\n- Do NOT change the code block color scheme (Night Owl)\n- Do NOT touch Layout.js or any other files\n- Do NOT add dark mode (separate concern)\n- Do NOT change the LANGUAGE_META colors in CodeBlock.js\n- Do NOT add new CSS rules — only modify existing property values","acceptance_criteria":"1. All `:root` color custom properties use oklch() syntax (no hex values remain for tokens listed above)\n2. The page background is near-white with a faint blue tint (visually similar to before but not pure white)\n3. Links are still blue and visually similar to before\n4. Callout boxes still show 4 distinct colors (blue info, orange warning, red danger, green success)\n5. Code blocks are unchanged (Night Owl dark blue background preserved)\n6. Header background is updated to oklch value\n7. Breadcrumb separator and blockquote border use oklch values\n8. `npm run build` in documentation/documentation/ succeeds without errors\n9. The site loads correctly in Chrome 111+ and Safari 15.4+ (oklch browser support baseline)","status":"open","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-20T18:20:31.538843+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:20:31.538843+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:31.54053+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:20:31.542591+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.3","title":"Update border radii and spacing to match scaffold","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate the border radius custom properties and a few spacing values to match the scaffold's more rounded, modern aesthetic.\n\n### 1. Update radius tokens in `:root`\n```css\n/* OLD → NEW */\n--radius-sm: 4px; → --radius-sm: 6px;\n--radius-md: 6px; → --radius-md: 8px;\n--radius-lg: 8px; → --radius-lg: 10px;\n```\n\nAlso add a new token after `--radius-lg`:\n```css\n--radius-xl: 14px;\n```\n\n### 2. Update the code block border-radius\nIn `.codeblock`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\nIn the fallback rule `.layout-content pre:not(.codeblock-pre)`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\n### 3. Update card-link border-radius\nIn `.card-link`, change:\n```css\nborder-radius: var(--radius-lg);\n```\nThis already uses the token — it will automatically pick up the new 10px value. No change needed.\n\n### 4. Update pagination-link border-radius\nIn `.pagination-link`, it already uses `var(--radius-lg)` — will pick up automatically.\n\n## Don't\n- Do NOT change any font, color, or typography properties\n- Do NOT change spacing tokens (--space-*) — they are fine as-is\n- Do NOT change the code block internal padding or header styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. --radius-sm is 6px, --radius-md is 8px, --radius-lg is 10px, --radius-xl is 14px in :root\n2. Code blocks have 10px border radius (inspect .codeblock element)\n3. Card links have 10px border radius\n4. Sidebar links have 8px border radius (--radius-md)\n5. Inline code still has rounded corners (uses --radius-sm = 6px now)\n6. `npm run build` succeeds without errors","status":"in_progress","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:20:48.238131+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:22:42.034305+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.3","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:48.239264+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.4","title":"Refine heading typography to match scaffold display style","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate heading styles to match the scaffold's Syne display typography conventions. The scaffold uses tighter letter-spacing and bolder heading hierarchy with Syne. These changes assume docs-1ho.1 (font loading) is already applied.\n\n### 1. Update `.layout-content h1`\nAdd `letter-spacing: -0.02em;` (tracking-tight in scaffold convention).\nKeep all other properties (font-size: 32px, font-weight: 700, etc.) unchanged.\n\n### 2. Update `.layout-content h2`\nAdd `letter-spacing: -0.01em;`.\nKeep all other properties unchanged.\n\n### 3. Update `.sidebar-section-header`\nChange from:\n```css\n.sidebar-section-header {\n font-size: 14px;\n font-weight: 600;\n text-transform: uppercase;\n color: var(--color-text-heading);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\nTo:\n```css\n.sidebar-section-header {\n font-size: 11px;\n font-weight: 700;\n text-transform: uppercase;\n letter-spacing: 0.08em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\n\nThis matches the scaffold's convention: sidebar section headers are smaller (11px), bolder (700), wider-tracked (0.08em), and use secondary color to feel like category labels rather than content headings.\n\n### 4. Update `.toc-title`\nChange `font-weight: 700` → `font-weight: 600` and add `font-family: var(--font-display);`\n\nThis gives the TOC \"On this page\" label the Syne display treatment.\n\n## Don't\n- Do NOT change font-size on h1, h2, h3, h4 (only add letter-spacing)\n- Do NOT change any colors (that is the colors task)\n- Do NOT change body text or paragraph styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. H1 has letter-spacing: -0.02em (inspect computed style)\n2. H2 has letter-spacing: -0.01em\n3. Sidebar section headers are 11px, font-weight 700, letter-spacing 0.08em, color is --color-text-secondary\n4. TOC title uses Syne (font-family: var(--font-display))\n5. No heading font sizes have changed from their current values\n6. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:21:05.00645+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:05.00645+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:05.008011+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:05.009956+08:00","created_by":"einstein.climateai.org"}]} From 770b46d5084aa0d4744d6a6a599daa5b2c9021c9 Mon Sep 17 00:00:00 2001 From: daviddao Date: Fri, 20 Feb 2026 18:25:15 +0800 Subject: [PATCH 6/7] beads: close docs-1ho.3 --- .beads/issues.jsonl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 8596068..ff7cb76 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -6,7 +6,7 @@ {"id":"docs-1ho","title":"Epic: Adopt scaffold visual design language for docs site","description":"Migrate the documentation site's visual design (fonts, colors, radii, typography, header) to match the hypercerts-scaffold-atproto design language. The scaffold uses Syne for display/headings, Outfit for body text, Geist Mono for code, an OKLCH indigo-tinted neutral palette, 10px base radius, and a refined modern aesthetic. The docs site currently uses system fonts, hex colors (#0570de accent), plain CSS with 4-8px radii, and a light-grey header. This epic updates the CSS custom properties and font loading — it does NOT introduce Tailwind or shadcn. The docs site stays plain CSS. Success: the docs site visually reads as the same brand as the scaffold app.","status":"open","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-20T18:19:37.842151+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:19:37.842151+08:00","labels":["scope:medium"]} {"id":"docs-1ho.1","title":"Load Syne, Outfit, and Geist Mono fonts","description":"## Files\n- documentation/components/Layout.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\n\n### 1. Add Google Fonts in Layout.js \u003cHead\u003e\nAdd a `\u003clink\u003e` tag inside the existing `\u003cHead\u003e` block to load Syne (400;500;600;700;800), Outfit (300;400;500;600;700), and Geist Mono (400;500) from Google Fonts.\n\nUse this exact URL:\n```\nhttps://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800\u0026family=Outfit:ital,wght@0,300;0,400;0,500;0,600;0,700\u0026family=Geist+Mono:wght@400;500\u0026display=swap\n```\n\nAdd both a `\u003clink rel=\"preconnect\"\u003e` for `fonts.googleapis.com` and `fonts.gstatic.com`, plus the stylesheet link. Place them BEFORE the existing `\u003cmeta\u003e` tags inside `\u003cHead\u003e`.\n\n### 2. Update CSS custom properties in globals.css\nReplace the existing `--font-sans` and `--font-mono` custom properties in the `:root` block:\n\n```css\n--font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n Helvetica, Arial, sans-serif;\n--font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n--font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco,\n Consolas, monospace;\n```\n\nNote: `--font-display` is a NEW custom property. Keep the system font fallbacks.\n\n### 3. Apply the display font to headings\nAdd these rules right after the existing `body { ... }` rule:\n\n```css\nh1, h2, h3, h4, h5, h6,\n.sidebar-section-header {\n font-family: var(--font-display);\n}\n```\n\nThis single rule applies Syne to all headings and sidebar section headers.\n\n## Don't\n- Do NOT remove any existing CSS rules\n- Do NOT change any font sizes, weights, or colors in this task (that is a separate task)\n- Do NOT add next/font — this project uses the Pages Router, use \u003clink\u003e tags\n- Do NOT add fonts to _app.js — they go in Layout.js \u003cHead\u003e\n- Do NOT touch any files other than Layout.js and globals.css","acceptance_criteria":"1. Visiting the docs site shows Outfit for body text (inspect body element, computed font-family starts with Outfit)\n2. All headings (h1-h6) render in Syne (inspect any h2, computed font-family starts with Syne)\n3. Code blocks render in Geist Mono (inspect a \u003ccode\u003e element, computed font-family starts with Geist Mono)\n4. Sidebar section headers render in Syne\n5. The Google Fonts link tag exists in the rendered HTML \u003chead\u003e\n6. Preconnect links exist for fonts.googleapis.com and fonts.gstatic.com\n7. globals.css defines three font custom properties: --font-sans, --font-display, --font-mono\n8. `npm run build` in documentation/documentation/ succeeds without errors","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-20T18:19:58.309568+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:24:39.028803+08:00","closed_at":"2026-02-20T18:24:39.028803+08:00","close_reason":"db0ab3a Load Syne, Outfit, and Geist Mono fonts","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.1","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:19:58.310671+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.2","title":"Migrate color palette to OKLCH indigo-tinted neutrals","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nReplace the hex color values in the `:root` CSS custom properties with OKLCH equivalents that match the scaffold's indigo-tinted neutral palette (hue ~260). This aligns the docs site with the scaffold's visual identity.\n\n### Replace these custom properties in `:root`:\n\n**Neutrals:**\n```css\n/* OLD → NEW */\n--color-bg: #ffffff; → --color-bg: oklch(0.995 0.001 260);\n--color-bg-subtle: #f6f8fa; → --color-bg-subtle: oklch(0.96 0.005 260);\n--color-border: #ebeef1; → --color-border: oklch(0.91 0.005 260);\n--color-border-strong: #d8dee4; → --color-border-strong: oklch(0.86 0.008 260);\n--color-text-primary: #414552; → --color-text-primary: oklch(0.40 0.015 260);\n--color-text-heading: #1a1b25; → --color-text-heading: oklch(0.20 0.01 260);\n--color-text-title: #1a1b25; → --color-text-title: oklch(0.16 0.005 260);\n--color-text-secondary: #687385;→ --color-text-secondary: oklch(0.55 0.01 260);\n--color-text-sidebar: #414552; → --color-text-sidebar: oklch(0.40 0.015 260);\n```\n\n**Accent / Links — keep the blue but express in OKLCH:**\n```css\n--color-link: #0570de; → --color-link: oklch(0.50 0.18 260);\n--color-link-hover: #0055bc; → --color-link-hover: oklch(0.43 0.19 260);\n--color-accent: #0570de; → --color-accent: oklch(0.50 0.18 260);\n```\n\n**Interaction colors (misc section):**\n```css\n--hover-bg: #f6f8fa; → --hover-bg: oklch(0.96 0.005 260);\n--active-bg: #f0f4ff; → --active-bg: oklch(0.95 0.015 260);\n--focus-ring: 0 0 0 4px rgba(5, 112, 222, 0.36); → --focus-ring: 0 0 0 4px oklch(0.50 0.18 260 / 0.36);\n```\n\n**Callout colors — keep the hues but express in OKLCH:**\n```css\n--color-info: #0570de; → --color-info: oklch(0.50 0.18 260);\n--color-info-bg: #f0f7ff; → --color-info-bg: oklch(0.96 0.02 260);\n--color-warning: #c84801; → --color-warning: oklch(0.55 0.17 55);\n--color-warning-bg: #fef9f0; → --color-warning-bg: oklch(0.97 0.02 80);\n--color-danger: #df1b41; → --color-danger: oklch(0.52 0.22 25);\n--color-danger-bg: #fef0f4; → --color-danger-bg: oklch(0.97 0.02 15);\n--color-success: #228403; → --color-success: oklch(0.52 0.17 145);\n--color-success-bg: #f0fef0; → --color-success-bg: oklch(0.97 0.03 145);\n```\n\n### Also update these hardcoded colors in other selectors:\n\n1. `.layout-header` background: change `#f6f8fa` → `oklch(0.985 0.002 260)` (scaffold's background tone for the header — near-white, matching the page body but with a faint warmth)\n\n2. `.breadcrumbs-separator` color: change `#a3acba` → `oklch(0.70 0.01 260)`\n\n3. `.layout-content blockquote` border-left color: change `#c0c8d2` → `oklch(0.80 0.01 260)`\n\n### DO NOT change these hardcoded colors (they are code-block-specific and should stay):\n- `#011627` (Night Owl background)\n- `#0d2137` (code block header)\n- `#1e3a5f` (code block border)\n- `#8899aa`, `#556677`, `#aabbcc` (code block UI elements)\n- Any `rgba(255, 255, 255, ...)` scrollbar colors inside code blocks\n\n## Don't\n- Do NOT change font families, font sizes, font weights, or spacing\n- Do NOT change the code block color scheme (Night Owl)\n- Do NOT touch Layout.js or any other files\n- Do NOT add dark mode (separate concern)\n- Do NOT change the LANGUAGE_META colors in CodeBlock.js\n- Do NOT add new CSS rules — only modify existing property values","acceptance_criteria":"1. All `:root` color custom properties use oklch() syntax (no hex values remain for tokens listed above)\n2. The page background is near-white with a faint blue tint (visually similar to before but not pure white)\n3. Links are still blue and visually similar to before\n4. Callout boxes still show 4 distinct colors (blue info, orange warning, red danger, green success)\n5. Code blocks are unchanged (Night Owl dark blue background preserved)\n6. Header background is updated to oklch value\n7. Breadcrumb separator and blockquote border use oklch values\n8. `npm run build` in documentation/documentation/ succeeds without errors\n9. The site loads correctly in Chrome 111+ and Safari 15.4+ (oklch browser support baseline)","status":"open","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-20T18:20:31.538843+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:20:31.538843+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:31.54053+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:20:31.542591+08:00","created_by":"einstein.climateai.org"}]} -{"id":"docs-1ho.3","title":"Update border radii and spacing to match scaffold","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate the border radius custom properties and a few spacing values to match the scaffold's more rounded, modern aesthetic.\n\n### 1. Update radius tokens in `:root`\n```css\n/* OLD → NEW */\n--radius-sm: 4px; → --radius-sm: 6px;\n--radius-md: 6px; → --radius-md: 8px;\n--radius-lg: 8px; → --radius-lg: 10px;\n```\n\nAlso add a new token after `--radius-lg`:\n```css\n--radius-xl: 14px;\n```\n\n### 2. Update the code block border-radius\nIn `.codeblock`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\nIn the fallback rule `.layout-content pre:not(.codeblock-pre)`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\n### 3. Update card-link border-radius\nIn `.card-link`, change:\n```css\nborder-radius: var(--radius-lg);\n```\nThis already uses the token — it will automatically pick up the new 10px value. No change needed.\n\n### 4. Update pagination-link border-radius\nIn `.pagination-link`, it already uses `var(--radius-lg)` — will pick up automatically.\n\n## Don't\n- Do NOT change any font, color, or typography properties\n- Do NOT change spacing tokens (--space-*) — they are fine as-is\n- Do NOT change the code block internal padding or header styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. --radius-sm is 6px, --radius-md is 8px, --radius-lg is 10px, --radius-xl is 14px in :root\n2. Code blocks have 10px border radius (inspect .codeblock element)\n3. Card links have 10px border radius\n4. Sidebar links have 8px border radius (--radius-md)\n5. Inline code still has rounded corners (uses --radius-sm = 6px now)\n6. `npm run build` succeeds without errors","status":"in_progress","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:20:48.238131+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:22:42.034305+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.3","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:48.239264+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.3","title":"Update border radii and spacing to match scaffold","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate the border radius custom properties and a few spacing values to match the scaffold's more rounded, modern aesthetic.\n\n### 1. Update radius tokens in `:root`\n```css\n/* OLD → NEW */\n--radius-sm: 4px; → --radius-sm: 6px;\n--radius-md: 6px; → --radius-md: 8px;\n--radius-lg: 8px; → --radius-lg: 10px;\n```\n\nAlso add a new token after `--radius-lg`:\n```css\n--radius-xl: 14px;\n```\n\n### 2. Update the code block border-radius\nIn `.codeblock`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\nIn the fallback rule `.layout-content pre:not(.codeblock-pre)`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\n### 3. Update card-link border-radius\nIn `.card-link`, change:\n```css\nborder-radius: var(--radius-lg);\n```\nThis already uses the token — it will automatically pick up the new 10px value. No change needed.\n\n### 4. Update pagination-link border-radius\nIn `.pagination-link`, it already uses `var(--radius-lg)` — will pick up automatically.\n\n## Don't\n- Do NOT change any font, color, or typography properties\n- Do NOT change spacing tokens (--space-*) — they are fine as-is\n- Do NOT change the code block internal padding or header styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. --radius-sm is 6px, --radius-md is 8px, --radius-lg is 10px, --radius-xl is 14px in :root\n2. Code blocks have 10px border radius (inspect .codeblock element)\n3. Card links have 10px border radius\n4. Sidebar links have 8px border radius (--radius-md)\n5. Inline code still has rounded corners (uses --radius-sm = 6px now)\n6. `npm run build` succeeds without errors","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:20:48.238131+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:25:12.922188+08:00","closed_at":"2026-02-20T18:25:12.922188+08:00","close_reason":"8d7ef9e Update border radii and spacing to match scaffold","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.3","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:48.239264+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.4","title":"Refine heading typography to match scaffold display style","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate heading styles to match the scaffold's Syne display typography conventions. The scaffold uses tighter letter-spacing and bolder heading hierarchy with Syne. These changes assume docs-1ho.1 (font loading) is already applied.\n\n### 1. Update `.layout-content h1`\nAdd `letter-spacing: -0.02em;` (tracking-tight in scaffold convention).\nKeep all other properties (font-size: 32px, font-weight: 700, etc.) unchanged.\n\n### 2. Update `.layout-content h2`\nAdd `letter-spacing: -0.01em;`.\nKeep all other properties unchanged.\n\n### 3. Update `.sidebar-section-header`\nChange from:\n```css\n.sidebar-section-header {\n font-size: 14px;\n font-weight: 600;\n text-transform: uppercase;\n color: var(--color-text-heading);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\nTo:\n```css\n.sidebar-section-header {\n font-size: 11px;\n font-weight: 700;\n text-transform: uppercase;\n letter-spacing: 0.08em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\n\nThis matches the scaffold's convention: sidebar section headers are smaller (11px), bolder (700), wider-tracked (0.08em), and use secondary color to feel like category labels rather than content headings.\n\n### 4. Update `.toc-title`\nChange `font-weight: 700` → `font-weight: 600` and add `font-family: var(--font-display);`\n\nThis gives the TOC \"On this page\" label the Syne display treatment.\n\n## Don't\n- Do NOT change font-size on h1, h2, h3, h4 (only add letter-spacing)\n- Do NOT change any colors (that is the colors task)\n- Do NOT change body text or paragraph styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. H1 has letter-spacing: -0.02em (inspect computed style)\n2. H2 has letter-spacing: -0.01em\n3. Sidebar section headers are 11px, font-weight 700, letter-spacing 0.08em, color is --color-text-secondary\n4. TOC title uses Syne (font-family: var(--font-display))\n5. No heading font sizes have changed from their current values\n6. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:21:05.00645+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:05.00645+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:05.008011+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:05.009956+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.5","title":"Add antialiased rendering and body font-weight","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nThe scaffold uses `antialiased` font rendering and Outfit at weight 400 for body text. The docs site already has `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` on body — but Outfit renders slightly differently than system fonts at the default weight. Add `font-weight: 400;` explicitly to the `body` rule to ensure consistent rendering with Outfit.\n\n### 1. In the `body { ... }` rule, add:\n```css\nfont-weight: 400;\n```\nPlace it after `font-size: 16px;`.\n\n### 2. Update the existing `body` line-height from `1.65` to `1.6`\nThe scaffold uses tighter line-height with Outfit. Change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n### 3. Update list item line-height to match\nIn `.layout-content article li`, change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n## Don't\n- Do NOT change any font-family properties\n- Do NOT change any colors\n- Do NOT change heading styles\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. Body element has font-weight: 400 in computed styles\n2. Body element has line-height: 1.6\n3. List items have line-height: 1.6\n4. Text renders with antialiased smoothing (already present, verify not removed)\n5. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-20T18:21:19.242335+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:19.242335+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:19.243605+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:19.245486+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-390","title":"Epic: Replace speculative blockchain/tokenization language with freeze-then-fund model across all docs","status":"closed","priority":1,"issue_type":"epic","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:19:57.096114+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T19:52:57.976277+13:00","closed_at":"2026-02-16T19:52:57.976277+13:00","close_reason":"Closed"} From 51aff19b2b0fc66c2e53f73df941beb510609642 Mon Sep 17 00:00:00 2001 From: daviddao Date: Fri, 20 Feb 2026 18:25:44 +0800 Subject: [PATCH 7/7] beads: claim docs-1ho.2 --- .beads/issues.jsonl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index ff7cb76..ecd4a99 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -5,10 +5,10 @@ {"id":"docs-150.4","title":"Mega CSS: all 25 Stripe parity fixes in globals.css","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nApply ALL of the following CSS changes to globals.css. Each change is numbered and references the current line. Read the file first to confirm line numbers, then apply all changes.\n\n### Design Token Changes (in :root block, lines 72-136)\n\n1. **Unify heading colors** — Change line 87 `--color-text-heading: #353a44` to `--color-text-heading: #1a1b25` and line 88 `--color-text-title: #21252c` to `--color-text-title: #1a1b25`\n\n2. **Content max-width** — Change line 110 `--content-max-width: 800px` to `--content-max-width: 880px`\n\n3. **TOC width** — Change line 109 `--toc-width: 200px` to `--toc-width: 250px`\n\n### Add responsive sidebar width (after the :root closing brace, ~line 136)\n\n4. **Sidebar responsive** — Add after the `:root` block:\n```css\n@media (min-width: 1400px) {\n :root {\n --sidebar-width: 280px;\n }\n}\n```\n\n### Header Changes (lines 175-221)\n\n5. **Header background** — Change line 181 from `background: rgba(255, 255, 255, 0.95)` to `background: #f6f8fa`. Remove lines 182-183 (`backdrop-filter` and `-webkit-backdrop-filter`).\n\n6. **Logo font-size** — Change line 196 `font-size: 15px` to `font-size: 16px`\n\n### Breadcrumb Changes (lines 223-268)\n\n7. **Breadcrumb font-size** — Change line 235 `font-size: 13px` to `font-size: 14px`\n\n8. **Breadcrumb separator** — Change line 245 `margin: 0 6px` to `margin: 0 8px`. Change line 246 `color: var(--color-text-secondary)` to `color: #a3acba`\n\n### Sidebar Changes (lines 275-439)\n\n9. **Sidebar content padding** — Change line 304 `padding: var(--space-6) 0` to `padding: var(--space-3) 0`\n\n10. **Sidebar section spacing** — Change line 350 `margin-top: var(--space-5)` to `margin-top: var(--space-4)` and line 351 `padding-top: var(--space-5)` to `padding-top: var(--space-4)`\n\n11. **Sidebar section header** — Change the `.sidebar-section-header` rule (lines 362-369):\n```css\n.sidebar-section-header {\n font-size: 12px;\n font-weight: 600;\n text-transform: uppercase;\n letter-spacing: 0.05em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-4);\n margin-bottom: var(--space-2);\n}\n```\n\n12. **Sidebar link density** — In `.sidebar-link` (lines 384-395), change `padding: 6px var(--space-3)` to `padding: 4px var(--space-2)` and change `border-radius: var(--radius-md)` to `border-radius: var(--radius-sm)`\n\n13. **Remove old sidebar-nav-link-row and sidebar-expand-btn rules** — Delete the `.sidebar-nav-link-row` rule (lines 379-382) and the `.sidebar-expand-btn` rules (lines 420-435). These are no longer used since the chevron is now inline.\n\n14. **Add sidebar-chevron styling** — Add after the `.sidebar-link` rules:\n```css\n.sidebar-chevron {\n flex-shrink: 0;\n margin-right: 4px;\n color: var(--color-text-secondary);\n}\n```\n\n15. **Add sidebar-link-toggle** — Add:\n```css\n.sidebar-link-toggle {\n cursor: pointer;\n}\n```\n\n16. **Sidebar link needs flex for inline chevron** — Add `display: flex; align-items: center;` to `.sidebar-link` (it currently has `display: block`). Change `display: block` to `display: flex` and add `align-items: center;`\n\n17. **Sidebar active link** — Change `.sidebar-link-active` (lines 403-407):\n```css\n.sidebar-link-active {\n color: var(--color-link);\n font-weight: 500;\n background: none;\n border-left: 2px solid var(--color-link);\n margin-left: -2px;\n}\n```\n\n18. **Sidebar parent-of-active** — Change `.sidebar-link-parent-active` (lines 415-418):\n```css\n.sidebar-link-parent-active {\n font-weight: 500;\n color: var(--color-text-primary);\n}\n```\n\n### Content Area Changes (lines 441-451)\n\n19. **Content padding** — Change line 446 `padding: var(--space-10) var(--space-12)` to `padding: var(--space-8) var(--space-10)` (32px top, 40px sides)\n\n### TOC Changes (lines 453-502)\n\n20. **TOC link font-size** — Change line 484 `font-size: 13px` to `font-size: 14px`\n\n21. **TOC link spacing** — Change line 483 `padding: var(--space-1) 0` to `padding: var(--space-2) 0`\n\n22. **TOC title margin** — Change line 474 `margin-bottom: var(--space-2)` to `margin-bottom: var(--space-4)`\n\n23. **Add TOC H3 indentation** — Add after the `.toc-link-active` rule:\n```css\n.toc-link-h3 {\n padding-left: 22px;\n font-size: 13px;\n}\n```\n\n24. **TOC responsive breakpoint** — Change line 878 `@media (max-width: 1100px)` to `@media (max-width: 1200px)`\n\n### Typography Changes (lines 556-705)\n\n25. **H1** — Remove `letter-spacing: -0.02em` from `.layout-content h1` (line 564)\n\n26. **H2** — Change `.layout-content h2` (lines 567-574): `font-size: 24px`, `line-height: 32px` (was 20px / 28px)\n\n27. **H3** — Change `.layout-content h3` (lines 576-583): `font-size: 16px`, `font-weight: 700` (was 18px / 600)\n\n28. **Paragraph spacing** — Change line 633 `margin-bottom: var(--space-4)` to `margin-bottom: var(--space-3)` (12px)\n\n29. **Bold text** — Change line 598 `font-weight: 600` to `font-weight: 700`\n\n30. **Inline code border** — In the inline code rule (lines 689-696), add `border: 1px solid var(--color-border)` and change `padding: 2px 6px` to `padding: 1px 4px`\n\n31. **Code blocks dark theme** — Change `.layout-content pre` (lines 671-681):\n```css\n.layout-content pre {\n background: #0a2540;\n padding: var(--space-4);\n border-radius: var(--radius-sm);\n overflow-x: auto;\n margin-bottom: var(--space-4);\n font-family: var(--font-mono);\n font-size: 13px;\n line-height: 19px;\n color: #f5fbff;\n}\n```\n\n32. **Code block scrollbar** — Update the code block scrollbar thumb colors (lines 47-54) to work on dark background: change `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)` and `rgba(0, 0, 0, 0.2)` to `rgba(255, 255, 255, 0.25)`. Also update the Firefox scrollbar-color on line 70 from `rgba(0, 0, 0, 0.12)` to `rgba(255, 255, 255, 0.15)`.\n\n33. **Blockquote** — Change `.layout-content blockquote` (lines 733-738): `border-left: 1px solid #c0c8d2` (was 4px solid var(--color-border)), `padding: 5px 0 5px 10px` (was 0 16px), add `font-size: 14px; line-height: 20px`\n\n34. **Table headers** — In `.layout-content th` (lines 714-720), add `text-transform: uppercase; font-size: 13px; letter-spacing: 0.03em`\n\n35. **Scrollbar gutter** — Add `scrollbar-gutter: stable;` to `.sidebar-content` (around line 303)\n\n### Link styling\n\n36. **Content links** — Change `.layout-content a` (lines 657-662): remove `border-bottom: 1px solid transparent` and add `text-decoration: underline; text-underline-offset: 2px; text-decoration-color: rgba(5, 112, 222, 0.4)`. Change `.layout-content a:hover` (lines 664-668): remove `border-bottom-color` line, change to `text-decoration-color: var(--color-link-hover)`\n\n## Test\n```bash\ncd documentation \u0026\u0026 node -e \"\nconst fs = require(\\\"fs\\\");\nconst css = fs.readFileSync(\\\"styles/globals.css\\\", \\\"utf8\\\");\nconst checks = [\n [css.includes(\\\"--color-text-heading: #1a1b25\\\"), \\\"heading color unified\\\"],\n [css.includes(\\\"--color-text-title: #1a1b25\\\"), \\\"title color unified\\\"],\n [css.includes(\\\"--content-max-width: 880px\\\"), \\\"content max-width 880\\\"],\n [css.includes(\\\"--toc-width: 250px\\\"), \\\"toc width 250\\\"],\n [css.includes(\\\"min-width: 1400px\\\"), \\\"responsive sidebar\\\"],\n [css.includes(\\\"background: #f6f8fa\\\") || css.includes(\\\"background:#f6f8fa\\\"), \\\"header solid bg\\\"],\n [css.includes(\\\"background: #0a2540\\\"), \\\"dark code blocks\\\"],\n [css.includes(\\\"color: #f5fbff\\\"), \\\"light code text\\\"],\n [css.includes(\\\"font-size: 13px\\\") \u0026\u0026 css.includes(\\\"line-height: 19px\\\"), \\\"code block sizing\\\"],\n [css.includes(\\\"toc-link-h3\\\"), \\\"toc h3 class\\\"],\n [css.includes(\\\"sidebar-chevron\\\"), \\\"sidebar chevron class\\\"],\n [css.includes(\\\"font-weight: 500\\\") \u0026\u0026 css.includes(\\\"sidebar-link-active\\\"), \\\"active link weight 500\\\"],\n [css.includes(\\\"border-left: 2px solid var(--color-link)\\\"), \\\"active left border\\\"],\n [css.includes(\\\"text-underline-offset\\\"), \\\"link underline style\\\"],\n [css.includes(\\\"scrollbar-gutter: stable\\\"), \\\"scrollbar gutter\\\"],\n [css.includes(\\\"max-width: 1200px\\\"), \\\"toc breakpoint 1200\\\"],\n [css.match(/\\\\.layout-content h2[^}]*font-size: 24px/s), \\\"h2 24px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-size: 16px/s), \\\"h3 16px\\\"],\n [css.match(/\\\\.layout-content h3[^}]*font-weight: 700/s), \\\"h3 weight 700\\\"],\n];\nlet pass = true;\nfor (const [ok, name] of checks) {\n if (!ok) { console.error(\\\"FAIL: \\\" + name); pass = false; }\n else { console.log(\\\"PASS: \\\" + name); }\n}\nif (!pass) process.exit(1);\nconsole.log(\\\"\\\\nAll CSS checks passed.\\\");\n\"\n```\n\n## Dont\n- Do not modify any component JS files\n- Do not change the mobile responsive rules (keep mobile padding as-is)\n- Do not remove any CSS rules that are still referenced by components (check before deleting)\n- Do not change the design token variable names, only their values","status":"closed","priority":1,"issue_type":"task","owner":"sharfy.adamantine@gmail.com","created_at":"2026-02-14T22:25:14.346526+13:00","created_by":"Sharfy Adamantine","updated_at":"2026-02-14T22:31:23.234686+13:00","closed_at":"2026-02-14T22:31:23.234686+13:00","close_reason":"2fda6b5 Applied all 36 CSS changes for Stripe design parity: unified heading colors, updated layout dimensions, improved sidebar/TOC styling, dark code blocks, enhanced typography, and responsive breakpoints","dependencies":[{"issue_id":"docs-150.4","depends_on_id":"docs-150","type":"parent-child","created_at":"2026-02-14T22:25:14.348237+13:00","created_by":"Sharfy Adamantine"}]} {"id":"docs-1ho","title":"Epic: Adopt scaffold visual design language for docs site","description":"Migrate the documentation site's visual design (fonts, colors, radii, typography, header) to match the hypercerts-scaffold-atproto design language. The scaffold uses Syne for display/headings, Outfit for body text, Geist Mono for code, an OKLCH indigo-tinted neutral palette, 10px base radius, and a refined modern aesthetic. The docs site currently uses system fonts, hex colors (#0570de accent), plain CSS with 4-8px radii, and a light-grey header. This epic updates the CSS custom properties and font loading — it does NOT introduce Tailwind or shadcn. The docs site stays plain CSS. Success: the docs site visually reads as the same brand as the scaffold app.","status":"open","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-20T18:19:37.842151+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:19:37.842151+08:00","labels":["scope:medium"]} {"id":"docs-1ho.1","title":"Load Syne, Outfit, and Geist Mono fonts","description":"## Files\n- documentation/components/Layout.js (modify)\n- documentation/styles/globals.css (modify)\n\n## What to do\n\n### 1. Add Google Fonts in Layout.js \u003cHead\u003e\nAdd a `\u003clink\u003e` tag inside the existing `\u003cHead\u003e` block to load Syne (400;500;600;700;800), Outfit (300;400;500;600;700), and Geist Mono (400;500) from Google Fonts.\n\nUse this exact URL:\n```\nhttps://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800\u0026family=Outfit:ital,wght@0,300;0,400;0,500;0,600;0,700\u0026family=Geist+Mono:wght@400;500\u0026display=swap\n```\n\nAdd both a `\u003clink rel=\"preconnect\"\u003e` for `fonts.googleapis.com` and `fonts.gstatic.com`, plus the stylesheet link. Place them BEFORE the existing `\u003cmeta\u003e` tags inside `\u003cHead\u003e`.\n\n### 2. Update CSS custom properties in globals.css\nReplace the existing `--font-sans` and `--font-mono` custom properties in the `:root` block:\n\n```css\n--font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n Helvetica, Arial, sans-serif;\n--font-display: 'Syne', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n--font-mono: 'Geist Mono', 'Source Code Pro', SFMono-Regular, Menlo, Monaco,\n Consolas, monospace;\n```\n\nNote: `--font-display` is a NEW custom property. Keep the system font fallbacks.\n\n### 3. Apply the display font to headings\nAdd these rules right after the existing `body { ... }` rule:\n\n```css\nh1, h2, h3, h4, h5, h6,\n.sidebar-section-header {\n font-family: var(--font-display);\n}\n```\n\nThis single rule applies Syne to all headings and sidebar section headers.\n\n## Don't\n- Do NOT remove any existing CSS rules\n- Do NOT change any font sizes, weights, or colors in this task (that is a separate task)\n- Do NOT add next/font — this project uses the Pages Router, use \u003clink\u003e tags\n- Do NOT add fonts to _app.js — they go in Layout.js \u003cHead\u003e\n- Do NOT touch any files other than Layout.js and globals.css","acceptance_criteria":"1. Visiting the docs site shows Outfit for body text (inspect body element, computed font-family starts with Outfit)\n2. All headings (h1-h6) render in Syne (inspect any h2, computed font-family starts with Syne)\n3. Code blocks render in Geist Mono (inspect a \u003ccode\u003e element, computed font-family starts with Geist Mono)\n4. Sidebar section headers render in Syne\n5. The Google Fonts link tag exists in the rendered HTML \u003chead\u003e\n6. Preconnect links exist for fonts.googleapis.com and fonts.gstatic.com\n7. globals.css defines three font custom properties: --font-sans, --font-display, --font-mono\n8. `npm run build` in documentation/documentation/ succeeds without errors","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-20T18:19:58.309568+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:24:39.028803+08:00","closed_at":"2026-02-20T18:24:39.028803+08:00","close_reason":"db0ab3a Load Syne, Outfit, and Geist Mono fonts","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.1","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:19:58.310671+08:00","created_by":"einstein.climateai.org"}]} -{"id":"docs-1ho.2","title":"Migrate color palette to OKLCH indigo-tinted neutrals","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nReplace the hex color values in the `:root` CSS custom properties with OKLCH equivalents that match the scaffold's indigo-tinted neutral palette (hue ~260). This aligns the docs site with the scaffold's visual identity.\n\n### Replace these custom properties in `:root`:\n\n**Neutrals:**\n```css\n/* OLD → NEW */\n--color-bg: #ffffff; → --color-bg: oklch(0.995 0.001 260);\n--color-bg-subtle: #f6f8fa; → --color-bg-subtle: oklch(0.96 0.005 260);\n--color-border: #ebeef1; → --color-border: oklch(0.91 0.005 260);\n--color-border-strong: #d8dee4; → --color-border-strong: oklch(0.86 0.008 260);\n--color-text-primary: #414552; → --color-text-primary: oklch(0.40 0.015 260);\n--color-text-heading: #1a1b25; → --color-text-heading: oklch(0.20 0.01 260);\n--color-text-title: #1a1b25; → --color-text-title: oklch(0.16 0.005 260);\n--color-text-secondary: #687385;→ --color-text-secondary: oklch(0.55 0.01 260);\n--color-text-sidebar: #414552; → --color-text-sidebar: oklch(0.40 0.015 260);\n```\n\n**Accent / Links — keep the blue but express in OKLCH:**\n```css\n--color-link: #0570de; → --color-link: oklch(0.50 0.18 260);\n--color-link-hover: #0055bc; → --color-link-hover: oklch(0.43 0.19 260);\n--color-accent: #0570de; → --color-accent: oklch(0.50 0.18 260);\n```\n\n**Interaction colors (misc section):**\n```css\n--hover-bg: #f6f8fa; → --hover-bg: oklch(0.96 0.005 260);\n--active-bg: #f0f4ff; → --active-bg: oklch(0.95 0.015 260);\n--focus-ring: 0 0 0 4px rgba(5, 112, 222, 0.36); → --focus-ring: 0 0 0 4px oklch(0.50 0.18 260 / 0.36);\n```\n\n**Callout colors — keep the hues but express in OKLCH:**\n```css\n--color-info: #0570de; → --color-info: oklch(0.50 0.18 260);\n--color-info-bg: #f0f7ff; → --color-info-bg: oklch(0.96 0.02 260);\n--color-warning: #c84801; → --color-warning: oklch(0.55 0.17 55);\n--color-warning-bg: #fef9f0; → --color-warning-bg: oklch(0.97 0.02 80);\n--color-danger: #df1b41; → --color-danger: oklch(0.52 0.22 25);\n--color-danger-bg: #fef0f4; → --color-danger-bg: oklch(0.97 0.02 15);\n--color-success: #228403; → --color-success: oklch(0.52 0.17 145);\n--color-success-bg: #f0fef0; → --color-success-bg: oklch(0.97 0.03 145);\n```\n\n### Also update these hardcoded colors in other selectors:\n\n1. `.layout-header` background: change `#f6f8fa` → `oklch(0.985 0.002 260)` (scaffold's background tone for the header — near-white, matching the page body but with a faint warmth)\n\n2. `.breadcrumbs-separator` color: change `#a3acba` → `oklch(0.70 0.01 260)`\n\n3. `.layout-content blockquote` border-left color: change `#c0c8d2` → `oklch(0.80 0.01 260)`\n\n### DO NOT change these hardcoded colors (they are code-block-specific and should stay):\n- `#011627` (Night Owl background)\n- `#0d2137` (code block header)\n- `#1e3a5f` (code block border)\n- `#8899aa`, `#556677`, `#aabbcc` (code block UI elements)\n- Any `rgba(255, 255, 255, ...)` scrollbar colors inside code blocks\n\n## Don't\n- Do NOT change font families, font sizes, font weights, or spacing\n- Do NOT change the code block color scheme (Night Owl)\n- Do NOT touch Layout.js or any other files\n- Do NOT add dark mode (separate concern)\n- Do NOT change the LANGUAGE_META colors in CodeBlock.js\n- Do NOT add new CSS rules — only modify existing property values","acceptance_criteria":"1. All `:root` color custom properties use oklch() syntax (no hex values remain for tokens listed above)\n2. The page background is near-white with a faint blue tint (visually similar to before but not pure white)\n3. Links are still blue and visually similar to before\n4. Callout boxes still show 4 distinct colors (blue info, orange warning, red danger, green success)\n5. Code blocks are unchanged (Night Owl dark blue background preserved)\n6. Header background is updated to oklch value\n7. Breadcrumb separator and blockquote border use oklch values\n8. `npm run build` in documentation/documentation/ succeeds without errors\n9. The site loads correctly in Chrome 111+ and Safari 15.4+ (oklch browser support baseline)","status":"open","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-20T18:20:31.538843+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:20:31.538843+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:31.54053+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:20:31.542591+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.2","title":"Migrate color palette to OKLCH indigo-tinted neutrals","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nReplace the hex color values in the `:root` CSS custom properties with OKLCH equivalents that match the scaffold's indigo-tinted neutral palette (hue ~260). This aligns the docs site with the scaffold's visual identity.\n\n### Replace these custom properties in `:root`:\n\n**Neutrals:**\n```css\n/* OLD → NEW */\n--color-bg: #ffffff; → --color-bg: oklch(0.995 0.001 260);\n--color-bg-subtle: #f6f8fa; → --color-bg-subtle: oklch(0.96 0.005 260);\n--color-border: #ebeef1; → --color-border: oklch(0.91 0.005 260);\n--color-border-strong: #d8dee4; → --color-border-strong: oklch(0.86 0.008 260);\n--color-text-primary: #414552; → --color-text-primary: oklch(0.40 0.015 260);\n--color-text-heading: #1a1b25; → --color-text-heading: oklch(0.20 0.01 260);\n--color-text-title: #1a1b25; → --color-text-title: oklch(0.16 0.005 260);\n--color-text-secondary: #687385;→ --color-text-secondary: oklch(0.55 0.01 260);\n--color-text-sidebar: #414552; → --color-text-sidebar: oklch(0.40 0.015 260);\n```\n\n**Accent / Links — keep the blue but express in OKLCH:**\n```css\n--color-link: #0570de; → --color-link: oklch(0.50 0.18 260);\n--color-link-hover: #0055bc; → --color-link-hover: oklch(0.43 0.19 260);\n--color-accent: #0570de; → --color-accent: oklch(0.50 0.18 260);\n```\n\n**Interaction colors (misc section):**\n```css\n--hover-bg: #f6f8fa; → --hover-bg: oklch(0.96 0.005 260);\n--active-bg: #f0f4ff; → --active-bg: oklch(0.95 0.015 260);\n--focus-ring: 0 0 0 4px rgba(5, 112, 222, 0.36); → --focus-ring: 0 0 0 4px oklch(0.50 0.18 260 / 0.36);\n```\n\n**Callout colors — keep the hues but express in OKLCH:**\n```css\n--color-info: #0570de; → --color-info: oklch(0.50 0.18 260);\n--color-info-bg: #f0f7ff; → --color-info-bg: oklch(0.96 0.02 260);\n--color-warning: #c84801; → --color-warning: oklch(0.55 0.17 55);\n--color-warning-bg: #fef9f0; → --color-warning-bg: oklch(0.97 0.02 80);\n--color-danger: #df1b41; → --color-danger: oklch(0.52 0.22 25);\n--color-danger-bg: #fef0f4; → --color-danger-bg: oklch(0.97 0.02 15);\n--color-success: #228403; → --color-success: oklch(0.52 0.17 145);\n--color-success-bg: #f0fef0; → --color-success-bg: oklch(0.97 0.03 145);\n```\n\n### Also update these hardcoded colors in other selectors:\n\n1. `.layout-header` background: change `#f6f8fa` → `oklch(0.985 0.002 260)` (scaffold's background tone for the header — near-white, matching the page body but with a faint warmth)\n\n2. `.breadcrumbs-separator` color: change `#a3acba` → `oklch(0.70 0.01 260)`\n\n3. `.layout-content blockquote` border-left color: change `#c0c8d2` → `oklch(0.80 0.01 260)`\n\n### DO NOT change these hardcoded colors (they are code-block-specific and should stay):\n- `#011627` (Night Owl background)\n- `#0d2137` (code block header)\n- `#1e3a5f` (code block border)\n- `#8899aa`, `#556677`, `#aabbcc` (code block UI elements)\n- Any `rgba(255, 255, 255, ...)` scrollbar colors inside code blocks\n\n## Don't\n- Do NOT change font families, font sizes, font weights, or spacing\n- Do NOT change the code block color scheme (Night Owl)\n- Do NOT touch Layout.js or any other files\n- Do NOT add dark mode (separate concern)\n- Do NOT change the LANGUAGE_META colors in CodeBlock.js\n- Do NOT add new CSS rules — only modify existing property values","acceptance_criteria":"1. All `:root` color custom properties use oklch() syntax (no hex values remain for tokens listed above)\n2. The page background is near-white with a faint blue tint (visually similar to before but not pure white)\n3. Links are still blue and visually similar to before\n4. Callout boxes still show 4 distinct colors (blue info, orange warning, red danger, green success)\n5. Code blocks are unchanged (Night Owl dark blue background preserved)\n6. Header background is updated to oklch value\n7. Breadcrumb separator and blockquote border use oklch values\n8. `npm run build` in documentation/documentation/ succeeds without errors\n9. The site loads correctly in Chrome 111+ and Safari 15.4+ (oklch browser support baseline)","status":"in_progress","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-20T18:20:31.538843+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:25:41.209858+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:31.54053+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.2","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:20:31.542591+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-1ho.3","title":"Update border radii and spacing to match scaffold","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate the border radius custom properties and a few spacing values to match the scaffold's more rounded, modern aesthetic.\n\n### 1. Update radius tokens in `:root`\n```css\n/* OLD → NEW */\n--radius-sm: 4px; → --radius-sm: 6px;\n--radius-md: 6px; → --radius-md: 8px;\n--radius-lg: 8px; → --radius-lg: 10px;\n```\n\nAlso add a new token after `--radius-lg`:\n```css\n--radius-xl: 14px;\n```\n\n### 2. Update the code block border-radius\nIn `.codeblock`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\nIn the fallback rule `.layout-content pre:not(.codeblock-pre)`, change:\n```css\nborder-radius: 8px; → border-radius: var(--radius-lg);\n```\n\n### 3. Update card-link border-radius\nIn `.card-link`, change:\n```css\nborder-radius: var(--radius-lg);\n```\nThis already uses the token — it will automatically pick up the new 10px value. No change needed.\n\n### 4. Update pagination-link border-radius\nIn `.pagination-link`, it already uses `var(--radius-lg)` — will pick up automatically.\n\n## Don't\n- Do NOT change any font, color, or typography properties\n- Do NOT change spacing tokens (--space-*) — they are fine as-is\n- Do NOT change the code block internal padding or header styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. --radius-sm is 6px, --radius-md is 8px, --radius-lg is 10px, --radius-xl is 14px in :root\n2. Code blocks have 10px border radius (inspect .codeblock element)\n3. Card links have 10px border radius\n4. Sidebar links have 8px border radius (--radius-md)\n5. Inline code still has rounded corners (uses --radius-sm = 6px now)\n6. `npm run build` succeeds without errors","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:20:48.238131+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:25:12.922188+08:00","closed_at":"2026-02-20T18:25:12.922188+08:00","close_reason":"8d7ef9e Update border radii and spacing to match scaffold","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.3","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:20:48.239264+08:00","created_by":"einstein.climateai.org"}]} -{"id":"docs-1ho.4","title":"Refine heading typography to match scaffold display style","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate heading styles to match the scaffold's Syne display typography conventions. The scaffold uses tighter letter-spacing and bolder heading hierarchy with Syne. These changes assume docs-1ho.1 (font loading) is already applied.\n\n### 1. Update `.layout-content h1`\nAdd `letter-spacing: -0.02em;` (tracking-tight in scaffold convention).\nKeep all other properties (font-size: 32px, font-weight: 700, etc.) unchanged.\n\n### 2. Update `.layout-content h2`\nAdd `letter-spacing: -0.01em;`.\nKeep all other properties unchanged.\n\n### 3. Update `.sidebar-section-header`\nChange from:\n```css\n.sidebar-section-header {\n font-size: 14px;\n font-weight: 600;\n text-transform: uppercase;\n color: var(--color-text-heading);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\nTo:\n```css\n.sidebar-section-header {\n font-size: 11px;\n font-weight: 700;\n text-transform: uppercase;\n letter-spacing: 0.08em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\n\nThis matches the scaffold's convention: sidebar section headers are smaller (11px), bolder (700), wider-tracked (0.08em), and use secondary color to feel like category labels rather than content headings.\n\n### 4. Update `.toc-title`\nChange `font-weight: 700` → `font-weight: 600` and add `font-family: var(--font-display);`\n\nThis gives the TOC \"On this page\" label the Syne display treatment.\n\n## Don't\n- Do NOT change font-size on h1, h2, h3, h4 (only add letter-spacing)\n- Do NOT change any colors (that is the colors task)\n- Do NOT change body text or paragraph styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. H1 has letter-spacing: -0.02em (inspect computed style)\n2. H2 has letter-spacing: -0.01em\n3. Sidebar section headers are 11px, font-weight 700, letter-spacing 0.08em, color is --color-text-secondary\n4. TOC title uses Syne (font-family: var(--font-display))\n5. No heading font sizes have changed from their current values\n6. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:21:05.00645+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:05.00645+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:05.008011+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:05.009956+08:00","created_by":"einstein.climateai.org"}]} -{"id":"docs-1ho.5","title":"Add antialiased rendering and body font-weight","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nThe scaffold uses `antialiased` font rendering and Outfit at weight 400 for body text. The docs site already has `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` on body — but Outfit renders slightly differently than system fonts at the default weight. Add `font-weight: 400;` explicitly to the `body` rule to ensure consistent rendering with Outfit.\n\n### 1. In the `body { ... }` rule, add:\n```css\nfont-weight: 400;\n```\nPlace it after `font-size: 16px;`.\n\n### 2. Update the existing `body` line-height from `1.65` to `1.6`\nThe scaffold uses tighter line-height with Outfit. Change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n### 3. Update list item line-height to match\nIn `.layout-content article li`, change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n## Don't\n- Do NOT change any font-family properties\n- Do NOT change any colors\n- Do NOT change heading styles\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. Body element has font-weight: 400 in computed styles\n2. Body element has line-height: 1.6\n3. List items have line-height: 1.6\n4. Text renders with antialiased smoothing (already present, verify not removed)\n5. `npm run build` succeeds without errors","status":"open","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-20T18:21:19.242335+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:21:19.242335+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:19.243605+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:19.245486+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.4","title":"Refine heading typography to match scaffold display style","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nUpdate heading styles to match the scaffold's Syne display typography conventions. The scaffold uses tighter letter-spacing and bolder heading hierarchy with Syne. These changes assume docs-1ho.1 (font loading) is already applied.\n\n### 1. Update `.layout-content h1`\nAdd `letter-spacing: -0.02em;` (tracking-tight in scaffold convention).\nKeep all other properties (font-size: 32px, font-weight: 700, etc.) unchanged.\n\n### 2. Update `.layout-content h2`\nAdd `letter-spacing: -0.01em;`.\nKeep all other properties unchanged.\n\n### 3. Update `.sidebar-section-header`\nChange from:\n```css\n.sidebar-section-header {\n font-size: 14px;\n font-weight: 600;\n text-transform: uppercase;\n color: var(--color-text-heading);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\nTo:\n```css\n.sidebar-section-header {\n font-size: 11px;\n font-weight: 700;\n text-transform: uppercase;\n letter-spacing: 0.08em;\n color: var(--color-text-secondary);\n padding: var(--space-1) var(--space-5);\n margin-bottom: var(--space-3);\n}\n```\n\nThis matches the scaffold's convention: sidebar section headers are smaller (11px), bolder (700), wider-tracked (0.08em), and use secondary color to feel like category labels rather than content headings.\n\n### 4. Update `.toc-title`\nChange `font-weight: 700` → `font-weight: 600` and add `font-family: var(--font-display);`\n\nThis gives the TOC \"On this page\" label the Syne display treatment.\n\n## Don't\n- Do NOT change font-size on h1, h2, h3, h4 (only add letter-spacing)\n- Do NOT change any colors (that is the colors task)\n- Do NOT change body text or paragraph styling\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. H1 has letter-spacing: -0.02em (inspect computed style)\n2. H2 has letter-spacing: -0.01em\n3. Sidebar section headers are 11px, font-weight 700, letter-spacing 0.08em, color is --color-text-secondary\n4. TOC title uses Syne (font-family: var(--font-display))\n5. No heading font sizes have changed from their current values\n6. `npm run build` succeeds without errors","status":"in_progress","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-20T18:21:05.00645+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:25:42.535235+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:05.008011+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.4","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:05.009956+08:00","created_by":"einstein.climateai.org"}]} +{"id":"docs-1ho.5","title":"Add antialiased rendering and body font-weight","description":"## Files\n- documentation/styles/globals.css (modify)\n\n## What to do\nThe scaffold uses `antialiased` font rendering and Outfit at weight 400 for body text. The docs site already has `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` on body — but Outfit renders slightly differently than system fonts at the default weight. Add `font-weight: 400;` explicitly to the `body` rule to ensure consistent rendering with Outfit.\n\n### 1. In the `body { ... }` rule, add:\n```css\nfont-weight: 400;\n```\nPlace it after `font-size: 16px;`.\n\n### 2. Update the existing `body` line-height from `1.65` to `1.6`\nThe scaffold uses tighter line-height with Outfit. Change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n### 3. Update list item line-height to match\nIn `.layout-content article li`, change:\n```css\nline-height: 1.65; → line-height: 1.6;\n```\n\n## Don't\n- Do NOT change any font-family properties\n- Do NOT change any colors\n- Do NOT change heading styles\n- Do NOT touch any files other than globals.css","acceptance_criteria":"1. Body element has font-weight: 400 in computed styles\n2. Body element has line-height: 1.6\n3. List items have line-height: 1.6\n4. Text renders with antialiased smoothing (already present, verify not removed)\n5. `npm run build` succeeds without errors","status":"in_progress","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-20T18:21:19.242335+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-20T18:25:43.699695+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho","type":"parent-child","created_at":"2026-02-20T18:21:19.243605+08:00","created_by":"einstein.climateai.org"},{"issue_id":"docs-1ho.5","depends_on_id":"docs-1ho.1","type":"blocks","created_at":"2026-02-20T18:21:19.245486+08:00","created_by":"einstein.climateai.org"}]} {"id":"docs-390","title":"Epic: Replace speculative blockchain/tokenization language with freeze-then-fund model across all docs","status":"closed","priority":1,"issue_type":"epic","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:19:57.096114+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T19:52:57.976277+13:00","closed_at":"2026-02-16T19:52:57.976277+13:00","close_reason":"Closed"} {"id":"docs-390.1","title":"Rewrite architecture/overview.md: replace blockchain ownership layer with freeze-then-fund model","description":"## Files\n- documentation/pages/architecture/overview.md (modify)\n\n## What to do\n\nUpdate all references to blockchain-based tokenization/ownership to reflect that:\n1. The tokenization layer has NOT been developed yet — it is TBD\n2. The theory and architecture are correct — freeze records, anchor on-chain, then fund\n3. The docs should present this as the intended design, not as something that exists today\n\nThe freeze-then-fund model:\n1. A hypercert starts as mutable ATProto records (activity claim + evidence + evaluations etc.)\n2. Before a hypercert can be funded, its ATProto records must be **frozen** — a snapshot of the current state is taken and anchored on-chain. This creates an immutable reference point.\n3. The reason: a funder must know exactly what they are funding. If the cert contents can still change after funding, the funder might end up paying for something different than what they signed up for.\n4. Once frozen and anchored on-chain, the hypercert can be listed for funding.\n5. Evaluations and evidence can still accumulate AFTER freezing — they are separate records that reference the frozen claim. But the core claim itself is immutable once frozen.\n\n### IMPORTANT FRAMING GUIDANCE\n- Do NOT strip out the blockchain/tokenization concept — the theory is right and the architecture is sound\n- DO make clear that the tokenization layer hasn't been built yet — it's TBD\n- Frame it as: \"the intended design is X\" or \"the planned approach is X\" — not as if it's live\n- Use phrases like \"the tokenization layer is not yet implemented\", \"this is the planned design\", \"the on-chain mechanisms are being designed\"\n- Keep the two-layer architecture (data layer + ownership/funding layer) — it's the right design\n- When describing how tokenization/funding WILL work, use future tense or \"planned\" language\n- The freeze-then-fund concept is the KEY insight to convey: you must freeze the cert before allowing funding\n\n### Specific changes needed:\n\n**Line 8:** Change \"combines AT Protocol for data portability with blockchain for ownership guarantees\" → something like \"combines AT Protocol for data portability with planned on-chain anchoring for ownership and funding guarantees.\" Make clear this is the design, not yet implemented.\n\n**Line 18 (Ownership Layer description):** Rewrite. The ownership layer is planned but not yet built. The intended design: frozen hypercert snapshots will be anchored on-chain so they can be funded. A hypercert cannot be funded while its contents are still changing — freezing ensures funders know exactly what they are paying for. Make clear this layer is TBD.\n\n**Lines 20-31 (stack diagram):** Update the bottom layer label. Add \"(planned)\" or similar to indicate it's not yet built.\n\n**Lines 63-81 (Ownership Layer Deep Dive):** Rewrite this section to describe the PLANNED design:\n- \"Anchoring\": Describe the planned approach — freezing the ATProto record state and anchoring the snapshot on-chain.\n- \"Tokenization\": Explain the planned approach — the specific on-chain mechanism (token standard, chain choice) is being designed. The concept: freeze the cert, anchor it, then enable funding.\n- \"Funding Mechanisms\": Keep the general concepts (direct purchase, retroactive funding, etc.) but frame as planned/intended, not implemented.\n- \"Multi-Chain Support\": Frame as intended design, not yet determined.\n\n**Lines 83-112 (How the Layers Connect):** Rewrite to describe the planned design:\n- The bridge will be: ATProto records are frozen, the snapshot CID is anchored on-chain, and funding operates against that frozen state.\n- Keep the cross-layer example but frame as \"how this will work\" not \"how this works.\"\n\n**Lines 114-136 (Key Design Decisions):**\n- \"Why Not Fully On-Chain?\" — Keep as-is, still valid.\n- \"Why Not Fully Off-Chain?\" — Rewrite to emphasize: without on-chain anchoring, there's no way to guarantee that what a funder pays for won't change. Freezing and anchoring provides the immutability guarantee.\n- \"Why This Separation?\" — Update to mention freeze-then-fund as the key planned mechanism.\n\n**Lines 138-148 (What This Enables):**\n- Frame enabled use cases as what the design WILL enable once the tokenization layer is built.\n\n### Key terminology:\n- Keep \"tokenization\" as a concept but mark as \"planned\" / \"not yet implemented\" / \"TBD\"\n- Use \"freeze\" / \"frozen\" / \"freezing\" to describe the new concept\n- Use future tense or \"planned\" language for anything on-chain\n- Keep \"funding\" language — the concept is real\n\n### Tone:\n- The architecture is sound, the theory is right\n- The tokenization layer just hasn't been built yet\n- Be clear about what exists (ATProto data layer) vs what's planned (on-chain ownership/funding layer)\n\n## Test\ngrep -q 'not yet\\|TBD\\|being designed\\|planned\\|will be' documentation/pages/architecture/overview.md \u0026\u0026 \\\ngrep -q 'freez' documentation/pages/architecture/overview.md \u0026\u0026 \\\ngrep -q 'funder.*know\\|know.*fund\\|change.*after\\|cannot.*funded.*changing\\|can.t.*funded.*chang\\|exactly what' documentation/pages/architecture/overview.md \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Remove the blockchain/tokenization concept entirely — the theory is right, keep it as the planned design\n- Present tokenization as if it's already implemented/live\n- Invent specific smart contract details or token standards that don't exist\n- Change the Data Layer section (lines 33-61) — that's accurate as-is\n- Change the \"Why ATProto Over IPFS\" section (126-130) — that's accurate","status":"closed","priority":1,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:20:42.512677+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T12:32:03.352974+13:00","closed_at":"2026-02-16T12:32:03.352974+13:00","close_reason":"9055496 Rewrite architecture/overview.md to reflect freeze-then-fund model and planned tokenization layer","labels":["scope:medium"],"dependencies":[{"issue_id":"docs-390.1","depends_on_id":"docs-390","type":"parent-child","created_at":"2026-02-16T12:20:42.514231+13:00","created_by":"sharfy-test.climateai.org"}]} {"id":"docs-390.2","title":"Rewrite architecture/data-flow-and-lifecycle.md: replace Stage 5 blockchain funding with freeze-then-fund","description":"## Files\n- documentation/pages/architecture/data-flow-and-lifecycle.md (modify)\n\n## What to do\n\nUpdate blockchain-centric language in the lifecycle doc. Key framing:\n1. The tokenization layer has NOT been developed yet — it is TBD\n2. The theory and architecture are correct — freeze records, anchor on-chain, then fund\n3. The docs should present this as the intended design, not as something that exists today\n\nThe freeze-then-fund model: before a hypercert can be funded, its ATProto records must be frozen (snapshotted and anchored on-chain). This protects funders — they need to know exactly what they're funding, and the cert contents must not change after funding.\n\n### IMPORTANT FRAMING GUIDANCE\n- Do NOT strip out the blockchain/tokenization concept — the theory is right and the architecture is sound\n- DO make clear that the tokenization layer hasn't been built yet — it's TBD\n- Frame it as: \"the intended design is X\" or \"the planned approach is X\" — not as if it's live\n- Use phrases like \"the tokenization layer is not yet implemented\", \"this is the planned design\", \"the on-chain mechanisms are being designed\"\n- When describing how tokenization/funding WILL work, use future tense or \"planned\" language\n- The freeze-then-fund concept is the KEY insight to convey\n\n### Specific changes:\n\n**Line 16 (Enrichment):** Change \"Rights records define what token holders receive\" → \"Rights records define what funders or stakeholders receive.\" (The concept of rights is correct, just don't assume tokens exist yet.)\n\n**Line 22 (Funding stage summary):** Rewrite. Current text presents tokenization as live. New text should describe the planned design: Before funding, the hypercert's ATProto records will be frozen — a cryptographic snapshot taken and anchored on-chain. This ensures funders know exactly what they are paying for. The cert's core content cannot change after freezing. The specific on-chain funding mechanisms are being designed.\n\n**Line 24 (Accumulation):** Update to reflect planned design. Evaluations and evidence continue accumulating around the frozen claim.\n\n**Line 29 (diagram):** Change \"Blockchain\" under Funding to \"On-chain (planned)\"\n\n**Line 69 (Rights records):** Change \"define what token holders receive\" → \"define what funders or stakeholders receive\"\n\n**Lines 146-181 (Stage 5: Funding \u0026 Ownership):** Rewrite this section to describe the PLANNED design:\n\n- **Anchoring:** Describe the planned approach — when a hypercert is ready for funding, its current ATProto state will be frozen. The snapshot CID is anchored on-chain. The reason: a funder must know exactly what they are funding.\n\n- **Tokenization → rename to \"Freezing and Immutability\":** Explain the planned concept. Once frozen, the core activity claim cannot be modified. Evidence and evaluations can still accumulate. The specific on-chain representation (token standard, contract design) is being designed. Note: the tokenization layer is not yet implemented, but the theory is sound.\n\n- **Funding Mechanisms:** Keep the general concepts but frame as planned. Various funding models are intended, including direct funding, retroactive funding, and impact certificates. The specific mechanisms are being designed.\n\n- **Multi-Chain Support:** Frame as intended design. The protocol plans to be chain-agnostic but specifics are TBD.\n\n- **Diagram:** Update to reflect planned state. Replace \"Token Contract\" / \"Token ID\" with planned equivalents like \"Frozen Snapshot\" / \"CID: bafyrei...\"\n\n**Lines 199-205 (Stage 6 - Ownership Transfers / Long-Term Value):**\n- Reframe around the planned design. The frozen on-chain anchor will persist independently. Remove language that presents token transfers as live. Frame as intended future behavior.\n\n**Line 212 (diagram):** Change \"Blockchain\" labels to \"On-chain (planned)\"\n\n### Key terminology:\n- Keep \"tokenization\" as a concept but mark as \"planned\" / \"not yet implemented\" / \"TBD\"\n- Use \"freeze\" / \"frozen\" / \"freezing\" to describe the new concept\n- \"funders\" instead of \"token holders\" where referring to people who fund\n- Use future tense or \"planned\" language for anything on-chain\n- Keep \"on-chain\" — blockchain IS the plan\n\n## Test\ngrep -q 'not yet\\|TBD\\|being designed\\|planned\\|will be' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\ngrep -q 'freez' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\ngrep -q 'cannot.*change\\|must not.*change\\|exactly what.*fund\\|know.*what.*pay\\|frozen' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\n! grep -q 'token holder' documentation/pages/architecture/data-flow-and-lifecycle.md \u0026\u0026 \\\necho \"PASS\" || echo \"FAIL\"\n\n## Don't\n- Remove the blockchain/tokenization concept entirely — the theory is right, keep it as the planned design\n- Present tokenization as if it's already implemented/live\n- Change Stages 1-4 (Creation, Enrichment, Evaluation, Discovery) unless they contain token holder language\n- Invent smart contract details\n- Change the Cross-PDS References section (lines 215-234) — that's accurate\n- Change the \"What This Flow Enables\" section (lines 236-246) unless it has token language","status":"closed","priority":1,"issue_type":"task","assignee":"sharfy-test.climateai.org","owner":"sharfy-test.climateai.org","created_at":"2026-02-16T12:21:20.091221+13:00","created_by":"sharfy-test.climateai.org","updated_at":"2026-02-16T12:31:55.410818+13:00","closed_at":"2026-02-16T12:31:55.410818+13:00","close_reason":"5d8ba48 Replace Stage 5 blockchain funding with freeze-then-fund model","labels":["scope:medium"],"dependencies":[{"issue_id":"docs-390.2","depends_on_id":"docs-390","type":"parent-child","created_at":"2026-02-16T12:21:20.092158+13:00","created_by":"sharfy-test.climateai.org"}]}