docs: site copy, SEO/GEO, and public README polish

.gitignore

@@ -44,3 +44,11 @@ Desktop.ini
 .notch/index/
 .notch/logs/
 .notch/private/
+
+# Local playground stores (do not commit personal .notch roots)
+# Keep fixtures/ and intentional demo stores tracked separately.
+
+# Site local artifacts
+site/public/test-results/
+site/node_modules/
+site/.wrangler/

docs/README.md

@@ -13,7 +13,7 @@ Task-shaped how-tos for the main flows.
 - [Targeted brief workflow](guides/targeted-brief-workflow.md) — scoped task briefs vs cross-boundary packets.
 - [MCP setup](guides/mcp-setup.md) — server flags, available tools, agent instruction packs.
 - [Continuation checkpoints](guides/continuation-checkpoints.md) — opt-in Claude task aggregation, compaction fallback, model-down StopFailure recovery, and resume confirmation.
-- [Release](guides/release.md) — version surfaces, manual npm publish (token + temp config), and release-check automation.
+- [Release](guides/release.md) — maintainer version surfaces, publish recipe, and release-check.
 
 ## Reference
 

docs/guides/release.md

@@ -114,33 +114,38 @@ Optional second token name for CI later: `3notch-cli-publish-gha` (no IP lock; s
 From the project root, with `package.json` already at the release version:
 
 ```bash
+# Publish from the tree you intend to ship (usually up-to-date main)
+git checkout main && git pull
+node -p "require('./package.json').version"   # confirm expected version
+
 npm run build
 npm run release:check
 
 # Paste token from 1Password when prompted (hidden input)
 read -rs "NPM_TOKEN?Paste npm token from 1Password: "
 echo
 export NPM_TOKEN
+test -n "$NPM_TOKEN" || { echo "empty token"; exit 1; }
 
 npm_cfg="$(mktemp)"
 chmod 600 "$npm_cfg"
-printf '%s\n' '//registry.npmjs.org/:_authToken=${NPM_TOKEN}' > "$npm_cfg"
+# Double quotes required so ${NPM_TOKEN} expands (single quotes write the literal text)
+printf '%s\n' "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "$npm_cfg"
 export NPM_CONFIG_USERCONFIG="$npm_cfg"
-trap 'rm -f -- "$npm_cfg"' EXIT
+trap 'rm -f -- "$npm_cfg"; unset NPM_TOKEN' EXIT
 
 npm whoami
 npm publish --access public
-
-unset NPM_TOKEN
+npm view @3notch/cli version
 npm run release:status -- --require-published
 ```
 
 What this does:
 
-- Keeps the token out of the project tree and out of your permanent user `.npmrc` if you prefer
+- Publishes the current checkout (not whatever happens to be on GitHub unless you pulled)
+- Keeps the token out of the project tree and out of a permanent project `.npmrc`
 - Uses a mode-`600` temp npm userconfig and deletes it on shell exit
-- Confirms identity before publish
-- Fails the status check until registry `latest` equals `package.json`
+- Confirms identity before publish; fails status check until registry `latest` equals `package.json`
 
 Dry-run (no registry write):
 

eslint.config.mjs

@@ -13,4 +13,14 @@ export default tseslint.config(
       'no-undef': 'off',
     },
   },
+  {
+    files: ['scripts/**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      globals: {
+        console: 'readonly',
+        fetch: 'readonly',
+        process: 'readonly',
+      },
+    },
+  },
 );

site/README.md

@@ -41,10 +41,15 @@ npm run dev
 
 This uses `npx serve` (no install needed). Open the URL, edit `public/index.html`, refresh.
 
+**Preview with `npm run dev`, not by opening HTML as a file.** The site uses root-absolute paths (`/docs/`, `/docs/docs.css`) so production and `serve` behave the same. `file://` will break those links.
+
 ---
 
 ## Deploy to Cloudflare Pages
 
+**Canonical path:** Wrangler → Cloudflare Pages project `3notch`.  
+There is no GitHub Pages workflow for this site in-repo. If you ever saw a GitHub deploy, it was one-off or external—not the maintained path.
+
 ### One-time setup
 
 1. **Create a Cloudflare account** at https://dash.cloudflare.com (free).
@@ -60,9 +65,10 @@ This uses `npx serve` (no install needed). Open the URL, edit `public/index.html
 
 ### Ship it
 
-From `site/`:
+From `site/` (after copy/version changes are on the branch you want live):
 
 ```bash
+cd site
 npm run deploy
 ```