From 197442f3e808cfcffa3f2af9b30ed49b6129919e Mon Sep 17 00:00:00 2001
From: kzoeps <kzoepa@gmail.com>
Date: Thu, 30 Jul 2026 17:15:18 +0600
Subject: [PATCH 1/4] docs: define hidden tool page visibility

---
 ...30-hide-cli-scaffold-hyperboards-design.md | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md

diff --git a/docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md b/docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md
new file mode 100644
index 0000000..1f4fc07
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md
@@ -0,0 +1,40 @@
+# Hide CLI, Scaffold, and Hyperboards pages
+
+## Goal
+
+Temporarily remove the Hypercerts CLI, Scaffold Starter App, and Hyperboards documentation pages from site discovery without deleting their source content or assets.
+
+## Visibility contract
+
+The following routes remain buildable and directly accessible:
+
+- `/tools/hypercerts-cli`
+- `/tools/scaffold`
+- `/tools/hyperboards`
+
+They will not appear in:
+
+- sidebar navigation or previous/next navigation
+- the header Tools destination
+- search results or curated search quick links
+- the generated sitemap
+- links from other documentation pages
+
+The surrounding documentation remains unchanged except where wording must be adjusted after removing an internal link. General references to the products and external project links remain in scope; this change hides the documentation routes rather than erasing the products from the documentation.
+
+## Implementation shape
+
+A shared page-visibility configuration will list the three hidden paths. Search-index and sitemap generation will read that configuration so a page can be shown again by removing one path from a single list. Navigation entries and internal links will be removed because those sources are authored statically.
+
+The header Tools link currently targets Scaffold. It will point to the first remaining visible Tools page instead.
+
+## Validation
+
+Automated tests will verify that:
+
+1. the three Markdown source files still exist;
+2. the generated search index excludes all three routes;
+3. the generated sitemap excludes all three routes; and
+4. no authored navigation or documentation link points to a hidden route.
+
+The normal test suite and production build must pass.

From 99326ac42b59d0142758773f5b3e738e8e881321 Mon Sep 17 00:00:00 2001
From: kzoeps <kzoepa@gmail.com>
Date: Thu, 30 Jul 2026 17:22:34 +0600
Subject: [PATCH 2/4] docs: hide CLI, Scaffold, and Hyperboards pages

---
 components/Layout.js                       |  2 +-
 components/SearchDialog.js                 |  1 -
 lib/generate-search-index.js               |  4 ++
 lib/generate-sitemap.js                    |  4 +-
 lib/navigation.js                          |  3 -
 lib/page-visibility.json                   |  7 +++
 pages/architecture/account-and-identity.md |  2 +-
 pages/getting-started/quickstart.md        |  4 +-
 pages/tools/hyperscan.md                   |  1 -
 test/hidden-tool-visibility.test.js        | 69 ++++++++++++++++++++++
 10 files changed, 86 insertions(+), 11 deletions(-)
 create mode 100644 lib/page-visibility.json
 create mode 100644 test/hidden-tool-visibility.test.js

diff --git a/components/Layout.js b/components/Layout.js
index 1aab698..35c9f7d 100644
--- a/components/Layout.js
+++ b/components/Layout.js
@@ -163,7 +163,7 @@ export default function Layout({ children, frontmatter }) {
           <span className="header-divider" aria-hidden="true" />
           <nav className="header-nav" aria-label="Main navigation">
             <Link href="/getting-started/quickstart" className="header-nav-link">Docs</Link>
-            <Link href="/tools/scaffold" className="header-nav-link">Tools</Link>
+            <Link href="/tools/hypercerts-agent-skills" className="header-nav-link">Tools</Link>
           </nav>
           <div style={{ flex: 1 }} />
           <button
diff --git a/components/SearchDialog.js b/components/SearchDialog.js
index b451eff..4cd15a0 100644
--- a/components/SearchDialog.js
+++ b/components/SearchDialog.js
@@ -26,7 +26,6 @@ const QUICK_LINK_PATHS = [
   '/getting-started/quickstart',
   '/core-concepts/what-is-hypercerts',
   '/core-concepts/hypercerts-core-data-model',
-  '/tools/scaffold',
   '/architecture/overview',
   '/reference/glossary',
 ];
diff --git a/lib/generate-search-index.js b/lib/generate-search-index.js
index a8c1279..e32ca2b 100644
--- a/lib/generate-search-index.js
+++ b/lib/generate-search-index.js
@@ -1,5 +1,6 @@
 const { readdirSync, statSync, readFileSync, writeFileSync } = require("fs");
 const { join, relative } = require("path");
+const { hiddenPaths } = require("./page-visibility.json");
 const {
   loadExternalDocsContent,
   parseMarkdownFrontmatter,
@@ -9,6 +10,7 @@ const {
 const PAGES_DIR = join(__dirname, "..", "pages");
 const OUTPUT = join(__dirname, "..", "public", "search-index.json");
 const MAX_BODY_LENGTH = 5000;
+const HIDDEN_PATHS = new Set(hiddenPaths);
 
 function walkDir(dir) {
   const results = [];
@@ -111,6 +113,8 @@ async function main() {
     const rel = "/" + relative(PAGES_DIR, file).replace(/\.md$/, "");
     const path = rel === "/index" ? "/" : rel;
 
+    if (HIDDEN_PATHS.has(path)) continue;
+
     const frontmatter = parseMarkdownFrontmatter(localContent, relative(PAGES_DIR, file));
     const title = getStringFrontmatterValue(frontmatter, "title");
     const description = getStringFrontmatterValue(frontmatter, "description");
diff --git a/lib/generate-sitemap.js b/lib/generate-sitemap.js
index 8a74e87..8a8683a 100644
--- a/lib/generate-sitemap.js
+++ b/lib/generate-sitemap.js
@@ -1,7 +1,9 @@
 const fs = require('fs');
 const path = require('path');
+const { hiddenPaths } = require('./page-visibility.json');
 
 const SITE_URL = 'https://docs.hypercerts.org';
+const HIDDEN_PATHS = new Set(hiddenPaths);
 
 function getPages(dir, base = '') {
   const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -26,7 +28,7 @@ function getPages(dir, base = '') {
 
 function generateSitemap() {
   const pagesDir = path.join(__dirname, '..', 'pages');
-  const pages = getPages(pagesDir);
+  const pages = getPages(pagesDir).filter((page) => !HIDDEN_PATHS.has(page));
 
   const today = new Date().toISOString().split('T')[0];
 
diff --git a/lib/navigation.js b/lib/navigation.js
index 4c05a5b..59b23ed 100644
--- a/lib/navigation.js
+++ b/lib/navigation.js
@@ -60,12 +60,9 @@ export const navigation = [
   {
     section: "Tools",
     children: [
-      { title: "Scaffold Starter App", path: "/tools/scaffold" },
-      { title: "Hypercerts CLI", path: "/tools/hypercerts-cli" },
       { title: "Agent Skills", path: "/tools/hypercerts-agent-skills" },
       { title: "Hyperindex", path: "/tools/hyperindex" },
       { title: "Hyperscan", path: "/tools/hyperscan" },
-      { title: "Hyperboards", path: "/tools/hyperboards" },
       { title: "Labelers", path: "/tools/labelers" },
     ],
   },
diff --git a/lib/page-visibility.json b/lib/page-visibility.json
new file mode 100644
index 0000000..40c0007
--- /dev/null
+++ b/lib/page-visibility.json
@@ -0,0 +1,7 @@
+{
+  "hiddenPaths": [
+    "/tools/hypercerts-cli",
+    "/tools/scaffold",
+    "/tools/hyperboards"
+  ]
+}
diff --git a/pages/architecture/account-and-identity.md b/pages/architecture/account-and-identity.md
index 3ee11b4..c9413f4 100644
--- a/pages/architecture/account-and-identity.md
+++ b/pages/architecture/account-and-identity.md
@@ -90,7 +90,7 @@ See [ePDS (extended PDS)](/architecture/epds) for integration examples, handle m
 
 For scripts, CLI tools, and server-side automation, use app passwords instead of your main password. App passwords are scoped credentials that can be revoked independently.
 
-Create one in your account settings at [certified.app](https://certified.app). Give it a descriptive name (e.g., "CI/CD pipeline" or "Local development"). If a credential is compromised, revoke just that app password — your main account stays secure. The [Hypercerts CLI](/tools/hypercerts-cli) uses app passwords for authentication.
+Create one in your account settings at [certified.app](https://certified.app). Give it a descriptive name (e.g., "CI/CD pipeline" or "Local development"). If a credential is compromised, revoke just that app password — your main account stays secure.
 
 {% callout type="warning" %}
 Never commit app passwords to version control. Use environment variables or a secrets manager.
diff --git a/pages/getting-started/quickstart.md b/pages/getting-started/quickstart.md
index e8429d7..1c4ef93 100644
--- a/pages/getting-started/quickstart.md
+++ b/pages/getting-started/quickstart.md
@@ -64,7 +64,7 @@ const { session } = await client.callback(new URLSearchParams(callbackQuery));
 const agent = new Agent(session);
 ```
 
-See the [AT Protocol OAuth documentation](https://atproto.com/specs/oauth) for full details on client metadata, session storage, and keyset configuration. For further info on how to set up OAuth you can check out [AT Protos node.js implementation tutorial](https://atproto.com/guides/oauth-cli-tutorial) or the [scaffold app](/tools/scaffold).
+See the [AT Protocol OAuth documentation](https://atproto.com/specs/oauth) for full details on client metadata, session storage, and keyset configuration. For a step-by-step Node.js example, see the [AT Protocol OAuth tutorial](https://atproto.com/guides/oauth-cli-tutorial).
 
 ## Create your first hypercert
 
@@ -347,8 +347,6 @@ Your hypercert is now created and stored on your PDS. The completion screen show
 ![Completion screen showing the finished hypercert](/images/scaffold/finalized-cert.png)
 *The hypercert is created and stored on your PDS.*
 
-For full details on the Scaffold app — including self-hosting, environment setup, and extending the codebase — see the [Scaffold app documentation](/tools/scaffold).
-
 ## Next steps
 
 Third parties can now [evaluate your hypercert](/getting-started/working-with-evaluations) by creating evaluation records and measurements on their own PDS.
diff --git a/pages/tools/hyperscan.md b/pages/tools/hyperscan.md
index 14e315d..9fefcdf 100644
--- a/pages/tools/hyperscan.md
+++ b/pages/tools/hyperscan.md
@@ -124,5 +124,4 @@ Use the Agent API when you want a tool, bot, or coding agent to understand the c
 
 - [Hyperindex](/tools/hyperindex) — indexer used to query and serve indexed Hypercerts data
 - [Labelers](/tools/labelers) — ATProto label services used for quality and trust signals
-- [Hypercerts CLI](/tools/hypercerts-cli) — command-line tool for creating and inspecting Hypercerts records
 - [Introduction to Lexicons](/lexicons/introduction-to-lexicons) — schemas behind the records shown in Hyperscan
diff --git a/test/hidden-tool-visibility.test.js b/test/hidden-tool-visibility.test.js
new file mode 100644
index 0000000..9589420
--- /dev/null
+++ b/test/hidden-tool-visibility.test.js
@@ -0,0 +1,69 @@
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const { existsSync, readFileSync, readdirSync } = require('node:fs');
+const { join, relative } = require('node:path');
+const test = require('node:test');
+
+const ROOT = join(__dirname, '..');
+const PAGES_DIR = join(ROOT, 'pages');
+const HIDDEN_PATHS = [
+  '/tools/hypercerts-cli',
+  '/tools/scaffold',
+  '/tools/hyperboards',
+];
+const HIDDEN_PAGE_FILES = new Set(HIDDEN_PATHS.map((path) => `pages${path}.md`));
+
+function walkMarkdownFiles(directory) {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name);
+    return entry.isDirectory() ? walkMarkdownFiles(path) : path.endsWith('.md') ? [path] : [];
+  });
+}
+
+test('keeps the hidden tool page source files', () => {
+  for (const file of HIDDEN_PAGE_FILES) {
+    assert.equal(existsSync(join(ROOT, file)), true, `${file} must remain available for direct routes`);
+  }
+});
+
+test('excludes hidden tool pages from the generated search index', () => {
+  execFileSync(process.execPath, ['lib/generate-search-index.js'], { cwd: ROOT });
+  const index = JSON.parse(readFileSync(join(ROOT, 'public/search-index.json'), 'utf8'));
+  const indexedHiddenPaths = index
+    .map((page) => page.path)
+    .filter((path) => HIDDEN_PATHS.includes(path));
+
+  assert.deepEqual(indexedHiddenPaths, []);
+});
+
+test('excludes hidden tool pages from the generated sitemap', () => {
+  execFileSync(process.execPath, ['lib/generate-sitemap.js'], { cwd: ROOT });
+  const sitemap = readFileSync(join(ROOT, 'public/sitemap.xml'), 'utf8');
+
+  for (const path of HIDDEN_PATHS) {
+    assert.doesNotMatch(sitemap, new RegExp(`<loc>[^<]+${path}</loc>`));
+  }
+});
+
+test('does not link to hidden tool pages from visible documentation or navigation', () => {
+  const authoredFiles = [
+    join(ROOT, 'components/Layout.js'),
+    join(ROOT, 'components/SearchDialog.js'),
+    join(ROOT, 'lib/navigation.js'),
+    ...walkMarkdownFiles(PAGES_DIR).filter((file) => {
+      const repoPath = relative(ROOT, file).split('\\').join('/');
+      return !HIDDEN_PAGE_FILES.has(repoPath);
+    }),
+  ];
+
+  for (const file of authoredFiles) {
+    const content = readFileSync(file, 'utf8');
+    for (const path of HIDDEN_PATHS) {
+      assert.equal(
+        content.includes(path),
+        false,
+        `${relative(ROOT, file)} still links to ${path}`,
+      );
+    }
+  }
+});

From 1f04cd28d0c8bfd819e9d64c266d175a969d7bd6 Mon Sep 17 00:00:00 2001
From: kzoeps <kzoepa@gmail.com>
Date: Thu, 30 Jul 2026 17:29:45 +0600
Subject: [PATCH 3/4] docs: remove implementation design artifact

---
 ...30-hide-cli-scaffold-hyperboards-design.md | 40 -------------------
 1 file changed, 40 deletions(-)
 delete mode 100644 docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md

diff --git a/docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md b/docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md
deleted file mode 100644
index 1f4fc07..0000000
--- a/docs/superpowers/specs/2026-07-30-hide-cli-scaffold-hyperboards-design.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Hide CLI, Scaffold, and Hyperboards pages
-
-## Goal
-
-Temporarily remove the Hypercerts CLI, Scaffold Starter App, and Hyperboards documentation pages from site discovery without deleting their source content or assets.
-
-## Visibility contract
-
-The following routes remain buildable and directly accessible:
-
-- `/tools/hypercerts-cli`
-- `/tools/scaffold`
-- `/tools/hyperboards`
-
-They will not appear in:
-
-- sidebar navigation or previous/next navigation
-- the header Tools destination
-- search results or curated search quick links
-- the generated sitemap
-- links from other documentation pages
-
-The surrounding documentation remains unchanged except where wording must be adjusted after removing an internal link. General references to the products and external project links remain in scope; this change hides the documentation routes rather than erasing the products from the documentation.
-
-## Implementation shape
-
-A shared page-visibility configuration will list the three hidden paths. Search-index and sitemap generation will read that configuration so a page can be shown again by removing one path from a single list. Navigation entries and internal links will be removed because those sources are authored statically.
-
-The header Tools link currently targets Scaffold. It will point to the first remaining visible Tools page instead.
-
-## Validation
-
-Automated tests will verify that:
-
-1. the three Markdown source files still exist;
-2. the generated search index excludes all three routes;
-3. the generated sitemap excludes all three routes; and
-4. no authored navigation or documentation link points to a hidden route.
-
-The normal test suite and production build must pass.

From b1985c38711c366e43044e626e670b4256521424 Mon Sep 17 00:00:00 2001
From: kzoeps <kzoepa@gmail.com>
Date: Thu, 30 Jul 2026 17:45:50 +0600
Subject: [PATCH 4/4] docs: archive hidden tool pages

---
 {pages => drafts}/tools/hyperboards.md    |  0
 {pages => drafts}/tools/hypercerts-cli.md |  0
 {pages => drafts}/tools/scaffold.md       |  0
 lib/generate-search-index.js              |  4 ---
 lib/generate-sitemap.js                   |  4 +--
 lib/page-visibility.json                  |  7 -----
 test/hidden-tool-visibility.test.js       | 35 ++++++-----------------
 7 files changed, 9 insertions(+), 41 deletions(-)
 rename {pages => drafts}/tools/hyperboards.md (100%)
 rename {pages => drafts}/tools/hypercerts-cli.md (100%)
 rename {pages => drafts}/tools/scaffold.md (100%)
 delete mode 100644 lib/page-visibility.json

diff --git a/pages/tools/hyperboards.md b/drafts/tools/hyperboards.md
similarity index 100%
rename from pages/tools/hyperboards.md
rename to drafts/tools/hyperboards.md
diff --git a/pages/tools/hypercerts-cli.md b/drafts/tools/hypercerts-cli.md
similarity index 100%
rename from pages/tools/hypercerts-cli.md
rename to drafts/tools/hypercerts-cli.md
diff --git a/pages/tools/scaffold.md b/drafts/tools/scaffold.md
similarity index 100%
rename from pages/tools/scaffold.md
rename to drafts/tools/scaffold.md
diff --git a/lib/generate-search-index.js b/lib/generate-search-index.js
index e32ca2b..a8c1279 100644
--- a/lib/generate-search-index.js
+++ b/lib/generate-search-index.js
@@ -1,6 +1,5 @@
 const { readdirSync, statSync, readFileSync, writeFileSync } = require("fs");
 const { join, relative } = require("path");
-const { hiddenPaths } = require("./page-visibility.json");
 const {
   loadExternalDocsContent,
   parseMarkdownFrontmatter,
@@ -10,7 +9,6 @@ const {
 const PAGES_DIR = join(__dirname, "..", "pages");
 const OUTPUT = join(__dirname, "..", "public", "search-index.json");
 const MAX_BODY_LENGTH = 5000;
-const HIDDEN_PATHS = new Set(hiddenPaths);
 
 function walkDir(dir) {
   const results = [];
@@ -113,8 +111,6 @@ async function main() {
     const rel = "/" + relative(PAGES_DIR, file).replace(/\.md$/, "");
     const path = rel === "/index" ? "/" : rel;
 
-    if (HIDDEN_PATHS.has(path)) continue;
-
     const frontmatter = parseMarkdownFrontmatter(localContent, relative(PAGES_DIR, file));
     const title = getStringFrontmatterValue(frontmatter, "title");
     const description = getStringFrontmatterValue(frontmatter, "description");
diff --git a/lib/generate-sitemap.js b/lib/generate-sitemap.js
index 8a8683a..8a74e87 100644
--- a/lib/generate-sitemap.js
+++ b/lib/generate-sitemap.js
@@ -1,9 +1,7 @@
 const fs = require('fs');
 const path = require('path');
-const { hiddenPaths } = require('./page-visibility.json');
 
 const SITE_URL = 'https://docs.hypercerts.org';
-const HIDDEN_PATHS = new Set(hiddenPaths);
 
 function getPages(dir, base = '') {
   const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -28,7 +26,7 @@ function getPages(dir, base = '') {
 
 function generateSitemap() {
   const pagesDir = path.join(__dirname, '..', 'pages');
-  const pages = getPages(pagesDir).filter((page) => !HIDDEN_PATHS.has(page));
+  const pages = getPages(pagesDir);
 
   const today = new Date().toISOString().split('T')[0];
 
diff --git a/lib/page-visibility.json b/lib/page-visibility.json
deleted file mode 100644
index 40c0007..0000000
--- a/lib/page-visibility.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "hiddenPaths": [
-    "/tools/hypercerts-cli",
-    "/tools/scaffold",
-    "/tools/hyperboards"
-  ]
-}
diff --git a/test/hidden-tool-visibility.test.js b/test/hidden-tool-visibility.test.js
index 9589420..51ee929 100644
--- a/test/hidden-tool-visibility.test.js
+++ b/test/hidden-tool-visibility.test.js
@@ -1,5 +1,4 @@
 const assert = require('node:assert/strict');
-const { execFileSync } = require('node:child_process');
 const { existsSync, readFileSync, readdirSync } = require('node:fs');
 const { join, relative } = require('node:path');
 const test = require('node:test');
@@ -11,7 +10,8 @@ const HIDDEN_PATHS = [
   '/tools/scaffold',
   '/tools/hyperboards',
 ];
-const HIDDEN_PAGE_FILES = new Set(HIDDEN_PATHS.map((path) => `pages${path}.md`));
+const ROUTE_PAGE_FILES = HIDDEN_PATHS.map((path) => `pages${path}.md`);
+const DRAFT_PAGE_FILES = HIDDEN_PATHS.map((path) => `drafts${path}.md`);
 
 function walkMarkdownFiles(directory) {
   return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
@@ -20,28 +20,12 @@ function walkMarkdownFiles(directory) {
   });
 }
 
-test('keeps the hidden tool page source files', () => {
-  for (const file of HIDDEN_PAGE_FILES) {
-    assert.equal(existsSync(join(ROOT, file)), true, `${file} must remain available for direct routes`);
+test('archives hidden tool pages outside the routable pages directory', () => {
+  for (const file of ROUTE_PAGE_FILES) {
+    assert.equal(existsSync(join(ROOT, file)), false, `${file} must not remain routable`);
   }
-});
-
-test('excludes hidden tool pages from the generated search index', () => {
-  execFileSync(process.execPath, ['lib/generate-search-index.js'], { cwd: ROOT });
-  const index = JSON.parse(readFileSync(join(ROOT, 'public/search-index.json'), 'utf8'));
-  const indexedHiddenPaths = index
-    .map((page) => page.path)
-    .filter((path) => HIDDEN_PATHS.includes(path));
-
-  assert.deepEqual(indexedHiddenPaths, []);
-});
-
-test('excludes hidden tool pages from the generated sitemap', () => {
-  execFileSync(process.execPath, ['lib/generate-sitemap.js'], { cwd: ROOT });
-  const sitemap = readFileSync(join(ROOT, 'public/sitemap.xml'), 'utf8');
-
-  for (const path of HIDDEN_PATHS) {
-    assert.doesNotMatch(sitemap, new RegExp(`<loc>[^<]+${path}</loc>`));
+  for (const file of DRAFT_PAGE_FILES) {
+    assert.equal(existsSync(join(ROOT, file)), true, `${file} must preserve the page source`);
   }
 });
 
@@ -50,10 +34,7 @@ test('does not link to hidden tool pages from visible documentation or navigatio
     join(ROOT, 'components/Layout.js'),
     join(ROOT, 'components/SearchDialog.js'),
     join(ROOT, 'lib/navigation.js'),
-    ...walkMarkdownFiles(PAGES_DIR).filter((file) => {
-      const repoPath = relative(ROOT, file).split('\\').join('/');
-      return !HIDDEN_PAGE_FILES.has(repoPath);
-    }),
+    ...walkMarkdownFiles(PAGES_DIR),
   ];
 
   for (const file of authoredFiles) {