From 296ce778bc0fb46cce60ef69caba91b3c195d128 Mon Sep 17 00:00:00 2001
From: Patrick Singletary <PSingletary@users.noreply.github.com>
Date: Sun, 6 Sep 2026 21:35:53 -0400
Subject: [PATCH] docs: save framework session state + review notes for
 PLAN-tool-er-framework

---
 docs/plans/PLAN-tool-er-framework.md          |  70 +++-
 .../framework-review/ATProtocol-Playground.md | 206 ++++++++++
 docs/plans/framework-review/SYNTHESIS.md      | 139 +++++++
 docs/plans/framework-review/_shared.md        | 357 +++++++++++++++++
 docs/plans/framework-review/extra-repos.md    | 206 ++++++++++
 docs/plans/framework-review/sifter.md         | 327 ++++++++++++++++
 docs/plans/framework-review/slicer.md         | 362 ++++++++++++++++++
 docs/plans/framework-review/verifier.md       | 351 +++++++++++++++++
 docs/plans/framework-review/zodiac.md         | 336 ++++++++++++++++
 9 files changed, 2351 insertions(+), 3 deletions(-)
 create mode 100644 docs/plans/framework-review/ATProtocol-Playground.md
 create mode 100644 docs/plans/framework-review/SYNTHESIS.md
 create mode 100644 docs/plans/framework-review/_shared.md
 create mode 100644 docs/plans/framework-review/extra-repos.md
 create mode 100644 docs/plans/framework-review/sifter.md
 create mode 100644 docs/plans/framework-review/slicer.md
 create mode 100644 docs/plans/framework-review/verifier.md
 create mode 100644 docs/plans/framework-review/zodiac.md

diff --git a/docs/plans/PLAN-tool-er-framework.md b/docs/plans/PLAN-tool-er-framework.md
index fd58aa6..d3a3ee8 100644
--- a/docs/plans/PLAN-tool-er-framework.md
+++ b/docs/plans/PLAN-tool-er-framework.md
@@ -116,9 +116,11 @@ registry.md + per-repo TODO.md (committed), so any session can resume.
 Phase 0 — Meta repo + baseline review (tooler)
 - Task 0.1: Create tooler repo on Tangled (git init, README, AGENTS.md from
   common template, LICENSE MIT, scaffold standard .gitignore). Verify: ls-remote.
-- Task 0.2: Copy /tmp/tangled-framework-review/notes/*.md into
-  tooler/docs/review/ (provenance; reviewers confirmed no secrets in notes).
-  Commit. Verify: file count 8, grep for <REDACTED> absence of real values.
+- Task 0.2: Copy the committed review notes from
+  ~/dev/_shared/docs/plans/framework-review/*.md (8 files, provenance; the
+  original /tmp/tangled-framework-review/notes/ copy is ephemeral — machine
+  reboot wipes it) into tooler/docs/review/. Commit. Verify: file count 8,
+  grep confirms no real secret values (reviewers already confirmed clean).
 - Task 0.3: Write registry.md (rows from section 2 table, status=planned),
   pins.md, DECISIONS.md (open questions from section 8).
 - Task 0.4: Write roles/orchestrator.md, roles/component-agent.md, roles/qa.md,
@@ -261,3 +263,65 @@ e) RESOLVED 2026-09-06 (owner, option c): tooler-dom DROPPED entirely —
   altifier (src/lib, src/contexts, package.json, tests).
 - This plan's home copy: ~/dev/_shared/docs/plans/PLAN-tool-er-framework.md
   (committed; moves to archive/ + REGISTRY.md row on pickup).
+
+---
+
+## 11. Session state and resume guide (last updated 2026-09-06)
+
+Status: PLANNED — review complete, plan authored and committed, NOT picked up,
+no build started. This section is the handoff point for any future session.
+
+### Progress log
+- 2026-09-06: Full read-only review of all 13 Tangled repos of psingletary.com
+  (7 parallel review agents, ~2,145 lines of notes, every claim file-cited).
+  All 13 repos cloned under ~/dev (notes: macos-sched-cleanup knot slug is
+  all-lowercase despite mixed-case display on the web UI — use the lowercase
+  SSH URL; spectroscopy is an empty repo, zero commits, nothing to extract).
+- 2026-09-06: Owner scope decision (a/b/c): include repos 1-5 (verifier,
+  altifier, slicer, sifter, timer) + web_themes. Dropped: ptharbor, acct-tools,
+  zodiac, daily-bsky-hype-vid, macOS-sched-cleanup, _shared (governance), and
+  ATProtocol-Playground (dropped option c after owner reviewed what it actually
+  contains: bsky.app DOM automation, zero protocol code).
+- 2026-09-06: Agent operating model confirmed (owner-specified): per-component
+  Tangled repos (web_themes model) so multiple agents improve repos in
+  parallel with tests; orchestrator agent coordinates all agents; QA tester
+  agent verifies; red-team agent audits across all repos. Roles docs ship in
+  the tooler meta repo (Phase 0 Task 0.4).
+- 2026-09-06: Plan authored and committed to _shared (617695c); tooler-dom
+  removed per decision c (258e3c7); review notes + this section committed
+  (see artifacts).
+
+### Artifacts (durable — all committed to Tangled _shared, public)
+- This plan: docs/plans/PLAN-tool-er-framework.md (258e3c7).
+- Review evidence: docs/plans/framework-review/*.md — 8 files (verifier,
+  slicer, sifter, zodiac, ATProtocol-Playground, extra-repos, _shared,
+  SYNTHESIS). SYNTHESIS.md is the condensed blueprint; per-repo files carry
+  the evidence. No secrets in any notes file (reviewers verified).
+- Source repos (all in ~/dev, clean mains): in-scope = verifier, altifier,
+  slicer, sifter, timer, web_themes. Out-of-scope but reviewed = ptharbor,
+  acct-tools, zodiac, daily-bsky-hype-vid, macOS-sched-cleanup,
+  ATProtocol-Playground, _shared.
+
+### Open decisions (owner answers at Phase 0 gate, a/b/c each)
+- a) Repo family naming: tooler-<module> vs alternatives.
+- b) Test runner for new lib repos: vitest (recommended) vs jest vs node:test.
+- c) Consumer install mechanism: npm git+ssh vs build-time sync (web_themes
+  pattern) vs vendor copy-in.
+- d) Consumer migration scope this cycle: all 5 apps vs reference consumers
+  only (recommended) vs no migrations.
+- e) RESOLVED: tooler-dom dropped (owner decision c).
+
+### Resume steps (next session, zero prior context)
+1. Session inbox lists this PLAN; owner says "pick up PLAN-tool-er-framework.md"
+   (never auto-pick-up).
+2. Owner answers decisions a-d.
+3. Run Phase 0: scaffold tooler meta repo on Tangled (public, psingletary.com);
+   copy docs/plans/framework-review/*.md into tooler/docs/review/ (source =
+   this committed copy, NOT /tmp); write registry.md / pins.md / DECISIONS.md;
+   write roles/{orchestrator,component-agent,qa,red-team}.md per section 3;
+   red-team agent baseline review of plan + 6 in-scope source repos (read-only),
+   findings to tooler/red-team-output/ (gitignored), RESOLVED inline before
+   Phase 1, open items to owner.
+4. Owner approval gate (section 5 Phase 0 gate) -> Phase 1 tooler-oauth.
+5. Per-repo pickup convention: after each phase completes, update registry.md
+   status column; this section's status line stays current.
diff --git a/docs/plans/framework-review/ATProtocol-Playground.md b/docs/plans/framework-review/ATProtocol-Playground.md
new file mode 100644
index 0000000..4f31482
--- /dev/null
+++ b/docs/plans/framework-review/ATProtocol-Playground.md
@@ -0,0 +1,206 @@
+# ATProtocol-Playground — Deep Review Notes (raw-material catalog for modular ATProto framework)
+
+Review date: 2026-09-06. Read-only review. No files modified.
+Repo: /Users/patricksingletary/dev/ATProtocol-Playground
+Remote: origin git@tangled.org:did:plc:vk25i3scormvs6kijn3sqzi7 (Tangled git host, ATProto-DID-keyed)
+Latest commit: a262241 "wip: snapshot during migration off OneDrive (2026-08-10)"; 8 commits total (2024-2026).
+
+## 0. CRITICAL FINDING (read first)
+
+Despite the name, ATProtocol-Playground contains ZERO protocol-level ATProto code.
+There is no XRPC call, no OAuth/PKCE/DPoP, no record create/update/delete, no
+blob/CID handling, no CAR files, no firehose/jetstream, no feed generator, no
+moderation/labeling, no PLC/did:web operations, no @atproto SDK usage (not even
+as a dependency — package.json has no runtime deps at all).
+
+Everything in this repo is CLIENT-SIDE manipulation of the bsky.app web frontend:
+- DOM element detection heuristics + CSS selector generation (tools/element-evaluator)
+- Tampermonkey userscripts that hide/remove/replace bsky.app DOM elements
+- A bulk-like bookmarklet/userscript that clicks Like buttons
+- A personal static site (wisp/) that happens to carry an atproto rel=me identity link
+- Python/HTML cookiecutter boilerplate leftovers (sample/, tests/*.py, docs/)
+
+The name is aspirational; the repo is really a "bsky.app UI tinkering" sandbox.
+For a protocol-level framework, this repo contributes UI/DOM-automation building
+blocks and one identity-verification snippet — not protocol methods. The other
+11 repos in the portfolio must supply the XRPC/auth/data-layer material.
+
+Git remote confirms the Tangled workflow: hosting keyed by a did:plc
+(did:plc:vk25i3scormvs6kijn3sqzi7).
+
+## 1. File inventory (line counts, one-line purpose)
+
+Top-level:
+- README.md (278) — full usage docs for Element Evaluator + BSky Cleaner; security note says never embed API keys/tokens/secrets (this is the only "token" hit in the repo — advisory text, not a secret). README also documents project structure that is now stale (see 6).
+- AGENTS.md (5) — agent convention: load `impeccable` skill for any frontend/UI work.
+- CHANGELOG.md (59) — [1.0.0] dated "2024-01-XX" (placeholder never finalized); lists evaluator tool, userscript, Puppeteer tests, docs, infra.
+- package.json (37) — see section 4.
+- tsconfig.json (27), jest.config.js (12), .eslintrc.json (22), .prettierrc.json (9), .gitignore (8), LICENSE (21, MIT per README), .DS_Store.
+- js/like.js (0 lines / 218 bytes) — minified URL-encoded bookmarklet one-liner.
+
+js/:
+- js/like.js — bookmarklet; decodes to: query all `button[aria-label^="Like ("]`, filter visible via `offsetParent`, click each. Bulk-like-all visible posts. Browser.
+
+tools/element-evaluator/ (TypeScript ESM, browser-targeted):
+- index.ts (13) — barrel: re-exports types.js, evaluator.js, dev-ui.js.
+- types.ts (72) — interfaces ElementCandidate (selector/text/role/confidence/meta), RuleAction union 'hide'|'remove'|'replace'|'annotate', Rule {selector, action, replaceText?, annotation?}, ScanOptions {roles, minConfidence, includeHidden}, ApplyRulesOptions {useMutationObserver, debounceMs, debug}. Clean, copy-paste-ready type model.
+- evaluator.ts (444) — core engine; see section 2 topic catalog.
+- dev-ui.ts (551) — class ElementEvaluatorDevUI: in-page overlay for scan/preview/rule-apply/export; exposes window.ElementEvaluatorDevUI + window.initElementEvaluatorDevUI. Includes injectStyles() with ~150 lines of inline CSS.
+- dev-example.html (106) — standalone demo page w/ mock bsky-like DOM (posts, bookmark/repost buttons, displayName).
+
+userscripts/ (all browser/Tampermonkey, @grant none):
+- bsky-cleaner.user.js (303) — config-driven DOM remover (remove/hide/replace), WeakSet dedupe, debounced MutationObserver. The flagship userscript.
+- bsky-socialapp-elementhider.js (365) — CSS-injection variant: builds one combined `display:none !important` rule, injects <style id>, re-injects if head is wiped by SPA nav; @run-at document-start.
+- ATProtoTweaks.js (96) — v1.72, oldest/most mature; CSS tweaks (enlarge like icon, hide follower count/bookmark) + injected pulsating bulk-like button in nav; has @downloadURL/@updateURL pointing at tangled.sh string URL (https://tangled.sh/strings/psingletary.com/3lw3oofrvgj22/raw).
+- COMPARISON_REPORT.md (600) — deep side-by-side of ATProtoTweaks vs bsky-cleaner: metadata, implementation approach, selector strategy, MutationObserver impl, config, quality, feature matrix, recommendations, tech-debt lists. Analyzes the repo's own scripts — useful as a decision doc pattern.
+- CSS_VS_DOM_MANIPULATION.md (406) — engineering analysis of the 3 hiding approaches (CSS rule vs JS style.setProperty vs element.remove()) incl. performance, FOUC, reversibility, hybrid approach + per-use-case recommendations.
+
+sample/ + tests/ + docs/ (Python/Sphinx boilerplate leftovers — NOT ATProto):
+- sample/__init__.py (0), sample/core.py (11) — `get_hmm()` returns 'hmmm...'; calls helpers.get_answer(); CRLF line endings (Windows heritage).
+- sample/helpers.py (2) — get_answer() returns True.
+- tests/test_basic.py (15), tests/test_advanced.py (15) — unittest suites that `from .context import sample`; there is NO context.py anywhere → these tests are broken as-is. Dead boilerplate (likely from a cookiecutter "sample" scaffold, kept despite the .gitignore Python cleanup commit).
+- docs/conf.py (241) — sphinx-quickstart boilerplate; header literally says "created by sphinx-quickstart on Mon Apr 16 21:22:43 2012". docs/index.rst (21) — empty Sphinx toctree. Dead.
+- These five files are the only Python in the repo and have zero ATProto content.
+
+tests/integration/ (Node + Puppeteer, ESM):
+- evaluator.test.js (240) — 5 tests; launches headless Chrome, loads test-fixtures.html; CAVEAT: it does NOT import evaluator.ts; it injects a simplified reimplementation via page.evaluate (lines 53-109) — so it tests a copy, not the shipped module.
+- userscript.test.js (236) — 5 tests; strips Tampermonkey header from bsky-cleaner.user.js then again re-implements rule logic inline instead of executing the script body; passes unused args to page.evaluate (e.g. `logs` array, line 148-163). Sloppy but exercises the same fixture.
+- test-fixtures.html (94) — mock bsky.app post layout: .post/.profile/.displayName/.handle, aria-label bookmark/repost/share buttons, data-testid variants, one hidden bookmark to test includeHidden. Good reusable fixture for DOM-level tests.
+
+wisp/ (static personal site — see section 5):
+- index.html (177), assets/main.js (2857, Carrd Site JS, MIT), assets/main.css (2591, generated), assets/icons.svg (15), assets/images/{favicon.png, apple-touch-icon.png, share.jpg, bg.jpg, bg.jpg}.
+
+Config:
+- jest.config.js, tsconfig.json, .eslintrc.json, .prettierrc.json, .gitignore — see section 4/6.
+
+## 2. TOPIC CATALOG (grouped by what actually exists)
+
+The requested framework topic buckets (auth, XRPC, records, blobs/CIDs, CAR,
+firehose/jetstream, feeds, moderation, identity ops, embeds, search, misc) have
+NO representation here. Actual topics, with all files:
+
+### T1. DOM element heuristic detection (bookmark/repost/displayname)
+- tools/element-evaluator/evaluator.ts — matchesBookmarkHeuristics(el) (line 79), matchesRepostHeuristics(el) (109), matchesDisplayNameHeuristics(el) (147): score from aria-label/title/alt/class/data-testid/text keyword sets + tag checks; confidence additive, threshold 0.5; evaluateElement(el) (189) returns ElementCandidate[]. Copy-paste-ready heuristic core, tightly coupled to bsky.app DOM vocabulary (aria-labels "Like (N)", data-testid="postBookmarkBtn", classes displayName/profile-name). Not ATProto-API knowledge; it is frontend-shape knowledge. To reuse for other targets, the keyword tables must be parameterized.
+- userscripts/*.js — same heuristic vocabulary expressed as CSS selectors ("button[aria-label*='Bookmark']", "[data-testid*='bookmark']", ".displayName" etc.), triplicated across the three scripts with slight drift.
+- tests/integration/test-fixtures.html — DOM fixture exercising the vocabulary.
+
+### T2. Unique CSS selector generation
+- tools/element-evaluator/evaluator.ts — generateSelector(el) (line 12): prefers id (CSS.escape), else walks up ancestors building tag#id/classes:nth-of-type chain, caps at depth 3 (path.length > 3 break at line 54). Comment says "enough specificity". Solid generic utility, fully reusable for any DOM-targeting tool (not bsky-specific).
+- Support: getElementText(el) (67) aria-label/title/alt/textContent fallback chain; dedupe by `selector::role` (296-304).
+
+### T3. Rule application + SPA mutation handling (hide/remove/replace/annotate)
+- tools/element-evaluator/evaluator.ts — applyRules(rules, options) (375): applies immediately, then MutationObserver on document.body (childList+subtree), debounced (default 300ms), returns {stop(), stats{totalApplied,lastRun}}; module-level singleton observer w/ cleanup. applyRule(rule, options) (328) uses style.setProperty('display','none','important'), element.remove(), textContent replace/annotate. This is the most framework-ready module: declarative-rule controller w/ lifecycle. Rough edges: singleton observer state (no multi-instance), no rule persistence, no re-query targeting.
+- userscripts/bsky-cleaner.user.js — productionized sibling: WeakSet processedElements dedupe (94), per-element dryRun logging (123-127), action fallback to SETTINGS.mode (116), setTimeout re-apply at 1s (295-297) for late content. JS-only duplicate of evaluator logic — one of the two should be the canonical impl.
+- userscripts/bsky-socialapp-elementhider.js — third implementation, CSS-based: buildCSS() joins selectors into one rule (101-147), injectCSS() id='bsky-element-hider-style' prepended to head (152), initMutationObserver watches head+body, re-injects only if style element vanished (246-313). Different perf/robustness trade-off than JS hide; documented in CSS_VS_DOM_MANIPULATION.md.
+- userscripts/CSS_VS_DOM_MANIPULATION.md — the design rationale doc for choosing among the three; recommend mining this into framework docs (decision tree CSS vs JS hide vs remove per use case, hybrid approach section lines 285-315).
+
+### T4. Bulk UI automation (like-all)
+- js/like.js — minified bookmarklet, single line: visible like-button clicker.
+- userscripts/ATProtoTweaks.js — addBulkLike() (70): injects #bulk-like-btn into nav[role="navigation"] guarded by existence check; on click spreads over visible `button[aria-label^="Like ("]` and clicks (81-85); MutationObserver-driven re-add (90-95). Working example of programmatic injection into a React SPA (nav exists after render; debounce 300ms).
+- Note: all bulk-like here is DOM clicking — none of it is XRPC (no com.atproto.repo.createRecord of app.bsky.feed.like). A framework like action would replace this with an API call.
+
+### T5. Userscript engineering patterns (Tampermonkey)
+- Metadata blocks in all three userscripts: @match lists covering bsky.app + third-party PDS frontends (sky.thebull.app, blacksky.community, catsky.social, thegems.app, bsky.gsheps.social, woof.blue, deer.social, zepplin.social, social.daniela.lol), @grant none, run-at document-idle vs document-start (cleaner) vs document-end (tweaks).
+- ATProtoTweaks.js has @downloadURL/@updateURL for auto-update (self-hosted on tangled.sh strings).
+- bsky-cleaner.user.js = documented SETTINGS block pattern (25-73) that README teaches users to edit. This is the canonical template for future "bsky UI" userscripts.
+
+### T6. In-browser dev tool UI
+- tools/element-evaluator/dev-ui.ts — ElementEvaluatorDevUI class: fixed overlay top-right, scan → candidate list with confidence %, per-candidate preview (outline highlight 3s) / hide / remove / replace, rules list w/ dedupe guard, Apply/Stop/Export JSON (Blob + anchor download, handleExportRules 356-370). escapeHtml via textContent div (375-379, XSS-safe). Global exports for console use (547-550). Rough: styles inlined in TS strings (getOverlayStyles + injectStyles ~150 lines), no shadow DOM, alert() for UX.
+- tools/element-evaluator/dev-example.html — standalone demo page to load dev UI against mock content.
+
+### T7. Headless browser test harness for DOM tooling
+- tests/integration/evaluator.test.js + userscript.test.js — Puppeteer headless launch boilerplate, page.setContent(fixture), $eval/$$eval assertions. Reusable harness skeleton; must be fixed to import the real modules (see section 6).
+- tests/integration/test-fixtures.html — bsky.app DOM mock, reusable.
+
+### T8. Static-site ATProto identity + embed (wisp/)
+- wisp/index.html line 20: `<link href="https://bsky.app/profile/did:plc:stznz7qsokto2345qtdzogjb" rel="me atproto">` — handle-verification rel=me pattern (site proves ownership of bsky profile). did:plc is a public identifier, not a secret. Framework-relevant for did:web/identity recipes.
+- wisp/index.html line 69: Bluesky timeline embed `<unloaded-script async src="https://bst.heion.net/timeline.js" data-handle="psingletary.com" data-theme="dark" ...>` — third-party embed widget pattern (alternative to oEmbed).
+- wisp/index.html contains the owner's public contact links (Mastodon, Signal, Discord, Teams, Cash App, PayPal, Venmo, calendly) — personal PII of a public profile page; fine in-repo but note the site is a deployable landing page.
+- assets/main.js is generic Carrd-generated site JS (MIT), assets/main.css generated template CSS, icons.svg sprite. Static hosting experiment (wisp.place per portfolio context) — nothing protocol-level.
+- This whole dir is a deployment experiment, not framework material, except the rel=me + embed snippets (T8).
+
+### T9. Dead boilerplate (no framework value)
+- sample/{__init__,core,helpers}.py, tests/test_basic.py, tests/test_advanced.py, docs/{conf.py,index.rst} — cookiecutter/Sphinx scaffold from 2012-era template; Python tests import a nonexistent .context module; CRLF endings. Should be pruned or ignored.
+
+## 3. Node vs browser context per file
+
+- Browser-only, DOM-required: tools/element-evaluator/*.ts (scanDocument uses document/window; compiles with tsconfig lib DOM; ESM with .js import specifiers), js/like.js, all userscripts/*.js, wisp/assets/main.js.
+- Node (test runner) driving browser: tests/integration/*.test.js (Puppeteer launches Chrome; NODE_OPTIONS=--experimental-vm-modules for jest ESM).
+- Python: sample/, tests/*.py (dead).
+- No file runs in both. No Deno/bun. Everything JS is untyped except the element-evaluator TS module.
+
+## 4. package.json + config (of-the-shelf versions)
+
+package.json: name atprotocol-playground v1.0.0, "type": "module". NO runtime dependencies. DevDependencies only:
+- typescript ^5.3.3, @types/node ^20.10.0, @types/jest ^29.5.11, @types/puppeteer ^5.4.10
+- jest ^29.7.0, jest-environment-node ^29.7.0, puppeteer ^21.6.0
+- eslint ^8.56.0, @typescript-eslint/parser+plugin ^6.15.0, eslint-config-prettier ^9.1.0, prettier ^3.1.1
+Scripts: build=tsc, dev=tsc --watch, test=`NODE_OPTIONS=--experimental-vm-modules jest`, test:integration=same + `--testMatch='**/tests/integration/**/*.test.js'`, lint=eslint, format=prettier --write.
+tsconfig.json: target ES2020, module ESNext, lib ES2020+DOM, moduleResolution node, strict, outDir dist, rootDir ./, declaration+declarationMap+sourceMap, include tools+** tests/**.
+jest.config.js: preset 'default' — NOT a real jest preset (jest ships none named 'default'; typical values are ts-jest/jest-expo or absent). transform: {} with extensionsToTreatAsEsm:['.ts'] but no TS transform present; moduleNameMapper strips .js → extensionless (for ESM TS imports). Since tests never import .ts, most of this config is inert; `preset: 'default'` is suspect and npm test likely errors on it. Flag for fix.
+.eslintrc.json: TS parser + recommended, prettier last; browser+node+es6 env; no-explicit-any warn. .prettierrc.json: semi, es5 trailing commas, single quote, width 100, 2-space. .gitignore: node_modules, dist, logs, .DS_Store, swp/swo, .cache, coverage.
+
+## 5. wisp/ directory assessment
+
+wisp/ = deployable static personal landing page ("Patrick Singletary", PSingletary brand), Carrd-style generated template (main.js header: "Carrd Site JS | carrd.co | License: MIT"), with hand-added ATProto touches:
+- rel="me atproto" identity link (index.html:20) for bsky handle verification,
+- heion.net Bluesky timeline embed (index.html:69),
+- sections home/tech/pay + Calendly + contact form (form posts to '#' — non-functional stub).
+Consistent with wisp.place static-hosting deployment experiments in the portfolio (see atproto-site-deployment skill context). Framework value: only the identity/embed snippets (T8). Rest is template CSS/JS noise.
+
+## 6. ROUGH / BROKEN / SUSPECT (framework-relevant caveats)
+
+1. tests/integration/evaluator.test.js — never imports evaluator.ts; tests an inline simplified reimplementation (lines 53-109). False confidence: module regressions would go uncaught. Must import the real module (needs proper jest TS transform or compile-first).
+2. tests/integration/userscript.test.js — same reimplementation pattern; extra page.evaluate args (coreLogic, logs) passed but unused (93, 148-163).
+3. jest.config.js — preset 'default' is not a shipped jest preset (suspect/broken); TS-transform config inert.
+4. tests/test_basic.py & test_advanced.py — import `sample.context` which does not exist; broken out of the box.
+5. docs/, sample/, tests/*.py — dead Sphinx/cookiecutter scaffold (2012-era conf.py header); CRLF files.
+6. README.md structure section (lines 148-164) is stale: omits js/, sample/, wisp/, userscripts/ATProtoTweaks.js + bsky-socialapp-elementhider.js, tests/*.py, docs/. README quick-start still references `path/to/dist/tools/element-evaluator/index.js` while dist/ is gitignored.
+7. CHANGELOG version date "2024-01-XX" never finalized; repo commits ran 2024→2026 but changelog has one entry.
+8. evaluator.ts dev-ui: singleton module-level MutationObserver/debounceTimer (369-370) — no multi-instance support; getOverlayStyles + injectStyles duplicate/embed ~150 lines CSS in TS strings.
+9. elementhider escapeSelector() (92-96) is a stub returning the selector unchanged (comment admits it). buildCSS combines selectors into one giant rule — an invalid selector anywhere kills the whole batch.
+10. Triple duplication of bsky selector vocabulary across bsky-cleaner.user.js, bsky-socialapp-elementhider.js, evaluator.ts, and ATProtoTweaks.js (4 copies, drifting). Centralize if reused.
+11. bsky-cleaner processedElements WeakSet (94) survives rules changes — if user removes a rule in SETTINGS mid-session the elements stay processed (only matters with reload-less toggles; minor).
+12. js/like.js is unreadable minified bookmarklet (deliberate — it is a bookmarklet — but keep source twin next to it).
+13. wisp/index.html contact form is non-functional (action="#").
+14. Secret hygiene: none found. grep across all code for api_key/secret/token/password/bearer/private keys returned only README.md advisory text ("Do not embed API keys, tokens, or secrets"). No credentials in repo. Personal public identifiers present: bsky did:plc (profile), tangled did:plc (git remote), author URLs, public contact links — public info, not secrets.
+
+## 7. Assessment vs the modular-framework goal
+
+What this repo can feed the framework (honestly bounded):
+- A declarative "detect → rule → apply-on-SPA" engine core (T1+T2+T3) reusable for any DOM-level Bluesky tooling, userscripts, or browser agents — plus the dev UI (T6) as a rule-authoring surface and the Puppeteer fixture harness (T7) as test scaffold. These need: parameterized heuristics (drop hardcoded bsky keyword tables), de-duplicated selector vocabulary, fixed test imports, fixed jest preset, extracted styles.
+- Design decision documentation (CSS_VS_DOM_MANIPULATION.md, COMPARISON_REPORT.md) that can be condensed into framework docs on DOM-modification strategy.
+- Tampermonkey packaging conventions incl. multi-PDS @match lists and tangled.sh-hosted auto-update URLs (T5) — relevant if the framework ships userscript templates.
+- rel=me atproto identity link snippet (wisp/index.html:20) and third-party timeline embed snippet (index.html:69) for identity/embed recipes.
+
+What it CANNOT supply: any protocol-layer module. Auth, XRPC transport, record
+lifecycle, blobs/CIDs/CAR, firehose/jetstream, feeds, moderation, PLC/did:web,
+search, richtext/embed canonical code — all absent. The framework must source
+these from the other ~10 repos (wisp.place deployments, tools with real API use,
+etc.). ATProtocol-Playground is best treated as the "browser/UI automation"
+slice of the catalog, NOT the flagship raw-material repo the name implies.
+
+## 8. Top framework candidates (see also summary block)
+
+Ranked, browser/DOM-focused:
+1. applyRules() declarative-rule controller w/ MutationObserver+debounce+stop/stats — evaluator.ts:375 — most framework-ready lifecycle module.
+2. generateSelector() unique-CSS-selector builder — evaluator.ts:12 — generic, portable, tested-by-use.
+3. Heuristic role matchers (bookmark/repost/displayname) — evaluator.ts:79-184 — needs parameterization; as-is the fastest path to a "bsky-element-detector" module.
+4. ElementCandidate/Rule/ScanOptions/ApplyRulesOptions type model — types.ts — clean schema for a rule JSON format (export/import already supported in dev-ui).
+5. CSS-injection hider w/ style-id + re-inject-on-head-wipe — bsky-socialapp-elementhider.js:83-313 — the robust SPA CSS pattern; extract to standalone "injectCSSRule(s)" helper.
+6. WeakSet dedupe + dryRun + debug + debounced-apply userscript core — bsky-cleaner.user.js — canonical userscript template.
+7. Bulk-like button injection w/ MutationObserver guard — ATProtoTweaks.js:70-95 — pattern for "inject control into SPA chrome".
+8. Bookmarklet encoding pattern — js/like.js.
+9. Dev overlay UI w/ JSON export + XSS-safe rendering — dev-ui.ts (extract styles; swap alert() for events).
+10. Puppeteer fixture harness + test-fixtures.html bsky DOM mock — tests/integration/ (fix imports first).
+11. Tampermonkey header template incl. multi-PDS @match + tangled.sh updateURL — userscripts/* headers.
+12. rel="me atproto" did:plc verification snippet — wisp/index.html:20.
+13. Bluesky timeline embed snippet (heion.net timeline.js) — wisp/index.html:69.
+14. Strict-ESM TS + eslint/prettier + jest/puppeteer toolchain template — package.json/tsconfig (fix jest preset).
+15. CSS-vs-JS-DOM-modification decision guide — userscripts/CSS_VS_DOM_MANIPULATION.md (mine into framework docs).
+
+## 9. Open items for parent agent
+
+- Confirm which portfolio repos actually contain protocol-level ATProto code; this one does not.
+- Decide whether bsky UI-automation (this repo's theme) is even in scope for the framework's MVP; if yes, fork T1/T2/T3/T6 into a "bluesky-dom-toolkit" module and canonicalize the selector vocabulary once.
+- If a userscript template ships in the framework, adopt bsky-cleaner.user.js SETTINGS block + ATProtoTweaks update-URL pattern.
diff --git a/docs/plans/framework-review/SYNTHESIS.md b/docs/plans/framework-review/SYNTHESIS.md
new file mode 100644
index 0000000..bab5340
--- /dev/null
+++ b/docs/plans/framework-review/SYNTHESIS.md
@@ -0,0 +1,139 @@
+# Tangled Repo Review — Synthesis for a Modular ATProto Framework
+
+Scope: all 13 public repos of psingletary.com on tangled.org + acct-tools (Tangled remote)
++ the shared layer. Repos reviewed in depth by 7 parallel reviewers; per-repo notes:
+verifier.md (verifier+altifier), slicer.md (slicer+timer), sifter.md (sifter+ptharbor),
+zodiac.md (zodiac+acct-tools), ATProtocol-Playground.md, extra-repos.md
+(daily-bsky-hype-vid + macos-sched-cleanup), _shared.md (_shared+web_themes).
+
+spectroscopy = empty repo (0 commits) — nothing to extract.
+
+## What the portfolio actually is
+
+12 real projects, four kinds:
+
+1. ATProto web tools (the core): verifier, altifier, slicer, sifter, timer — all CRA
+   React SPAs, all use atproto OAuth (BrowserOAuthClient) + Agent for XRPC, all
+   deployed via wispctl --spa. verifier+altifier are literal forks (bytes-identical
+   core), sifter vendor/ lifted auth+layout from verifier.
+2. Frontier specs: acct-tools (spec-only: "Deck" account toolkit), ptharbor
+   (planning-only: small-biz ATProto migration + did:web blueprint).
+3. Non-ATProto useful: zodiac (Next.js static, token-in-URL shares), macos-sched-cleanup
+   (launchd shell), daily-bsky-hype-vid (Python public-API fetcher).
+4. ATProtocol-Playground: NOT protocol code — bsky.app DOM automation (userscripts,
+   selectors, rule engine). Zero XRPC/auth/records. Supplies only the browser-UI slice.
+5. Infrastructure: _shared (AGENTS generator, plan intake, 43 skills, backup bin),
+   web_themes (theme package + sync).
+
+Key fact: only ONE repo (daily-bsky-hype-vid) uses raw public-api fetch; every app
+goes through @atproto/api Agent + BrowserOAuthClient. acct-tools spec mandates the
+newer @bsky/sdk + @atproto/lex line, calling @atproto/api legacy. Two version lines in
+the wild: 0.13.35/oauth 0.3.30 (CJS, jest hacks) vs 0.20.41/oauth 0.5.4 (ESM, zero-config) —
+timer S0 spike proved the latter bundles clean under CRA/webpack.
+
+## The ten framework modules that emerged (cross-repo consensus)
+
+M1 OAuth SPA bootstrap kit — AuthContext + fetched client-metadata.json + Login/
+   LoginCallback/ProtectedRoute(+Logout) + safeReturnUrl guard. Byte-identical across
+   verifier/altifier/slicer/sifter/timer; param scope (transition:generic vs chat.bsky).
+   Two callback styles: 0.3.30 explicit /login/callback route vs 0.5.4 auto-callback.
+   -> single shared module saves ~200 lines x 5 apps.
+
+M2 Auth'd XRPC data-access layer — cursor paginator (paginate(fn,params,onPage),
+   verifier), chunk + applyWrites-200 batcher (verifier P1, timer lists, acct-tools
+   spec), getProfiles x25, records read/create/update/delete + swapRecord-guarded
+   in-place edit (altifier P1) + validate:false retry (sifter). The "do X to all
+   records" verbs every tool needs.
+
+M3 Account-analysis engine — sifter scan.js (DI-injected paged scan: listBlobs /
+   describeRepo / listRecords / listMissingBlobs -> {trustworthy, held, referenced,
+   orphans, missing}, fail-closed) + extractBlobRefs (only generic walker for all blob
+   shapes incl. hydrated CIDs) + resumable-scan localStorage pattern (altifier).
+   Base for sifter/altifier/acct-tools F3/F5.
+
+M4 Blob lifecycle — blob deletion is impossible directly; the known method is
+   "reference then delete": create throwaway record in temp NSID -> deleteRecord ->
+   verify via listBlobs (sifter cleanup.js, acct-tools F3 spec). Upload: uploadBlob xN
+   -> createRecord w/ BlobRef + $type discriminator (slicer publish.js). Backup: getBlob
+   normalization + jszip manifest zip (sifter backup.js).
+
+M5 Publishing/composer — gallery pipeline (slicer publish.js: uploadBlob xN, $type
+   items, selfLabels, lexicon pre-validation) + verify.js "publish -> poll hydration ->
+   auto-delete on failure" + alt-text composer + a11y gating (alt.js). Post/media embed
+   normalization (parseEmbed: images / recordWithMedia / video) from altifier.
+
+M6 Headless bot template — timer bot/: app-password login, better-sqlite3 WAL,
+   5-min poll, paginated reads, INSERT OR IGNORE idempotency, DM send, opt-out on
+   400/403 + schema.sql. Plus launchd install/uninstall kit (macos-sched-cleanup
+   install.sh + plist template) for scheduling on macOS.
+
+M7 Image/media pipeline — slicer encode.js (single drawImage, WebP q binary search,
+   global long-edge reduction, EXIF), geometry.js (N-divisible grids), cropViewport.js
+   (pure pan/zoom math), carousel.js; rules: never upscale, identical dims, integer px.
+   Generalize beyond slicer; media gen for daily-bsky-hype-vid (ffmpeg timeline.py)
+   is per-run AI-generated, not committed.
+
+M8 Theme package — web_themes single theme (witchsky-cyan) with a 15-token :root
+   contract + var()-only gate (no hex outside :root) + build-time pull
+   (scripts/sync-theme.sh, shallow clone to ~/.cache) + ThemeContext dark mode.
+   Consumed at build time by verifier/altifier/sifter; never forked.
+
+M9 Identity/keys — did:web kit: Secp256k1Keypair keygen, did.json template
+   (JsonWebKey2020, AtprotoPersonalDataServer serviceEndpoint), serving options,
+   DNS, rotation/custody (ptharbor did-web-serving.md); key convention
+   ~/.config/<app>/did-web-private-key.hex 0o600 never in git; didUtils (plc.directory
+   + did:web resolution). Next frontier: acct-tools keys.ts (dual-curve, did:key +
+   Multikey, service-auth JWT ES256K/ES256 low-S) + PLC op submit flow.
+
+M10 Scaffold/governance — the missing link: project-init.sh + ~/templates/*.tmpl +
+   plan intake (PLAN -> scaffold -> TODO.md -> REGISTRY) + AGENTS overlay generator
+   (AGENTS.common.md + AGENTS.<repo>.md -> gen-agents.zsh) + .gitignore key blocklist
+   + theme sync hook + wispctl deploy conventions. project-init.sh lives in $HOME,
+   NOT versioned — highest-value first target.
+
+Cross-cutting conventions to encode (evidence everywhere): no emojis; secrets only in
+Bitwarden/Keychain, never quoted in code; no hardcoded hex colors; AGENTS.md primary
+(.hermes.md secondary); red-team-output/ gitignored + co-located findings with
+RESOLVED/REJECTED disposition; wispctl deploy --path build --site <x> --spa (db
+~/.config/wispctl/state.sqlite), Tangled push = backup only (timer AGENTS.md corrects
+stale claims that push deploys); pure DI-injected libs with tests, thin UI shells.
+
+## Baseline pins for a new app
+
+atproto/api 0.20.41 + oauth-client-browser 0.5.4 (proven zero-config under CRA/webpack;
+Jest needs no hacks at 0.20.x). Legacy CJS line 0.13.35 + oauth 0.3.30 only if stuck
+on react-scripts <5 or needing jest multiformats shims. Frontier: @bsky/sdk +
+@atproto/lex (acct-tools spec) — lex-first, api legacy.
+
+## Open decisions (owner)
+
+1. Framework home: new Tangled repo (e.g. atproto-framework / _shared-tools?) vs
+   promote _shared/tools/ (currently empty, declared "future integrations").
+2. Extraction style: copy-in (vendor/, the proven mechanism) vs published package
+   (npm workspace) vs git submodule. Copy-in is what the portfolio actually does.
+3. M1-M5 scope for first release vs all 10; DOM-automation slice from
+   ATProtocol-Playground in or out of scope.
+4. acct-tools "Deck" spec: build it as the reference consumer (it specifies the
+   lex/xrpc layer M2 almost exactly) or let the framework be extracted standalone.
+
+Notes dir: /tmp/tangled-framework-review/notes/ (8 files, ~2150 lines). Review was
+read-only; 3 repos cloned locally (daily-bsky-hype-vid, macos-sched-cleanup,
+spectroscopy-empty); spectroscopy left as-is (placeholder).
+
+================================================================================
+OWNER SCOPING (2026-09-06): include repos 1-5, 11, 13
+  verifier, altifier, slicer, sifter, timer, web_themes, ATProtocol-Playground
+EXCLUDED: ptharbor (did:web M9), acct-tools (lex-first M2 spec), zodiac,
+  daily-bsky-hype-vid, macOS-sched-cleanup (launchd kit), _shared (governance M10)
+Consequences:
+  - M9 identity/keys module drops out entirely (was ptharbor+acct-tools only).
+  - M2 baseline stays on atproto/api 0.20.41 + oauth-client-browser 0.5.4 (timer-proven);
+    no lex-first mandate since acct-tools spec is out.
+  - M10 scaffold/governance has no _shared source: framework repo must carry its own
+    conventions (AGENTS.md, gitignore key blocklist, wispctl deploy) — the 5 CRA apps
+    are mutually consistent, so extract from them directly.
+  - ATProtocol-Playground IN SCOPE => framework gains a second slice:
+    bluesky-dom-toolkit (applyRules rule controller, generateSelector, userscript
+    core, CSS-injection hider, dev overlay, Puppeteer fixture harness).
+  - No launchd scheduler in scope (macOS-sched-cleanup out) — bot scheduling stays
+    macOS-manual/PM2 unless added later.
diff --git a/docs/plans/framework-review/_shared.md b/docs/plans/framework-review/_shared.md
new file mode 100644
index 0000000..8b62f33
--- /dev/null
+++ b/docs/plans/framework-review/_shared.md
@@ -0,0 +1,357 @@
+# _shared infrastructure repo review (+ web_themes, _shared-local, _shared-redteam)
+
+Review date: 2026-09-06. Read-only review. Path base `~/dev` = /Users/patricksingletary/dev.
+Purpose: identify reusable framework components for a modular ATProto tooling framework.
+No secrets reproduced anywhere; secret-bearing artifacts flagged by filename only.
+
+================================================================================
+1. _shared  (~/dev/_shared)  — CROSS-PROJECT SHARED LAYER
+================================================================================
+
+Git: origin git@tangled.org:did:plc:gbmu2edwp7u7dva6x62gpgre (repo-DID URL; stable
+across handle changes). Public repo — every rule about secrets assumes world-readable
+remote (AGENTS.md:4-5; config/backup3/README.md). Last commit 2026-09-06.
+NOTE: ~/dev/_shared/README.md is STALE — describes an old OneDrive "hermes/1"
+layout (scripts/smart_chat.sh etc.) that no longer matches the actual tree;
+AGENTS.md is the authoritative entry point.
+
+Top level: AGENTS.md (primary agent instructions), AGENTS.common.md (shared
+template), AGENTS.ptharbor.md + AGENTS.zodiac.md (per-repo overlays), plan.md
+(machine setup playbook), README.md (stale), bin/ (13 tools), scripts/ (5 bash),
+skills/ (43 skills in 11 category dirs + SKILLS-INDEX.md), config/ (reference
+configs only), docs/ (guides + plans + atproto-digest), red-team-output/
+(gitignored), tools/ (EMPTY — declared "future tools/integrations").
+
+## 1.1 Agent-instruction system (the AGENTS overlay mechanism)
+
+- AGENTS.common.md — 5-line shared template: "AGENTS.md is the primary agent
+  instructions file; .hermes.md (if present) is secondary" + mandatory rule:
+  load `impeccable` skill first for ANY frontend/UI work. Contains {{REPO}}
+  placeholder for repo name.
+- bin/gen-agents.zsh — regenerates every repo's AGENTS.md under ~/dev from
+  AGENTS.common.md (+ optional AGENTS.<repo>.md extra block appended verbatim;
+  {{REPO}} = dir name). Writes only when content differs. Usage:
+  `gen-agents.zsh` (all repos) or `gen-agents.zsh stats zodiac`.
+- Per-repo overlays present: AGENTS.zodiac.md (security/secret-handling rules —
+  see 1.7) and AGENTS.ptharbor.md (migration plan pointer + red-team reviewer
+  standing instructions: read `.hermes/plans/README_red_team.md` before any work;
+  red_team_*.md findings are binding sequencing overrides).
+- _shared's own AGENTS.md = common block + plan-intake rules + a condensed
+  security block (rules 1-5, see 1.7).
+=> Framework method: repo overlays = common template + optional per-repo block,
+regenerated by a single script. Consumers (any new ~/dev project) get uniform
+agent instructions with repo-specific extras.
+
+## 1.2 Plan intake system (docs/plans/)
+
+- Inbox dir for Claude/Kagi-generated PLAN-*.md files; pickup is EXPLICIT-USER-
+  REQUEST ONLY. Hard rules (AGENTS.md + docs/plans/README.md + REGISTRY.md):
+  NEVER auto-pick-up; never auto-build (cost control — every build consumes
+  credits; user curates all projects).
+- Pickup flow: read plan -> `~/scripts/project-init.sh` scaffolds ~/dev/<slug>
+  (scaffold only, zero features) -> write TODO.md breakdown -> report project ID
+  -> move PLAN to docs/plans/archive/ -> add row to docs/plans/REGISTRY.md
+  (plan -> project ID -> status; statuses inbox/scaffold/building/done).
+- Live registry rows: sifter=building, timer=building, slicer=scaffold,
+  acct-tools=scaffold(hold), atproto-ecosystem-skills=done (docs/plans/REGISTRY.md).
+- docs/plans/TODO-redteam-2026-08-17.md — one-off red-team follow-up tracker.
+- atproto-digest project completed via this system: 897 URLs -> 10 skills
+  (docs/atproto-digest/TODO.md shows the phased pair-wise build w/ HARD STOPs,
+  classification.json, catalog.md, deepdive-list.md, notes/). Working example of
+  the digest->skill pipeline the framework could reuse for its own knowledge base.
+
+## 1.3 skills/ — canonical portable skill store (43 skills, 11 categories)
+
+Source of truth for the user's Hermes + Claude Code skills. Real dirs live HERE;
+~/.hermes/skills/* and ~/.agents/skills/* contain SYMLINKS pointing here
+(verified: .hermes links -> ~/dev/_shared/skills/...; ~/.agents/skills links ->
+.../software-development/*). SKILLS-INDEX.md documents the routing table and the
+re-link recipe (`ln -sfn ~/dev/_shared/skills/<cat>/<name> ~/.hermes/skills/...`).
+Convention: edit ~/dev/_shared/skills/ directly, commit+push; re-link on new
+machines (machine state, not in git). Category dirs and purposes:
+
+- autonomous-ai-agents/: hermes-session-maintenance (clean stale Hermes sessions
+  in state.db), hermes-skill-visibility (diagnose skill visible/not on a platform).
+- bitwarden-credential-store/: store+retrieve API keys via `bw` CLI; one Bitwarden
+  item per credential, fetched at runtime, never committed.
+- credential-management/: secrets across Bitwarden CLI + macOS Keychain + PKCE
+  flows; sensitivity table: master password -> Keychain `security
+  add-generic-password`, API key+secret -> ~/.config/bw/env (0600),
+  service creds -> Bitwarden login items.
+- devops/: atproto-site-deployment (static sites to Tangled git + wisp.place via
+  wispctl; OAuth session DB at ~/.config/wispctl/state.sqlite), external-skill-install
+  (install Claude Code skills into Hermes), secure-local-credential-infrastructure
+  (macOS credential/MCP hardening; patterns closed real red-team findings).
+- hermes-macos-project-setup/: full new-machine setup — Tangled SSH, Porkbun MCP
+  creds in Bitwarden+Keychain, Zed tasks, security hardening.
+- impeccable/: mandatory first load for any frontend design/polish/audit work.
+- note-taking/: context-file-management (consolidate files into a session context file).
+- productivity/: bitwarden-cli (bw API-key retrieval for MCP wrappers + scripts),
+  project-bootstrap (config-driven project-init.sh pipeline), project-organization.
+- research/: kagi-cli (Kagi search/assistant/translate via kagi-cli).
+- software-development/ (24 skills): 10 ATProto ecosystem skills from the digest
+  (ecosystem-map umbrella router + relays-firehose, jetstream-providers, pds-ops,
+  lexicon-registry, identity-deep, feeds-algorithms, moderation-tools,
+  security-landscape, tools-catalog) + atproto-attestation, atproto-cid,
+  atproto-development, atproto-oauth, atproto-repository (CAR/MST/DRISL),
+  bluesky-post-embeds, semble-cosmik, small-business-atproto-migration +
+  generic-dev: adversarial-red-team-review, adversarial-red-team-remediation,
+  document-variance-review, feature-reduction-planning, repository-structure-
+  analysis, macos-file-provider-workarounds, multi-machine-hermes-setup,
+  shell-scripting, zed-task-authoring, zed-tasks, zed-tasks-and-keymaps.
+- stats/: lottery-pipeline (VA lottery data -> optimized playslips), no-emojis
+  (never use emojis in code/docs/comments/generated text).
+- NOTE: many ~/.hermes/skills categories are NOT mirrored in _shared (email/,
+  github/, social-media/, web/, some devops skills like backup-move-scripts,
+  launchd-agent-ops, macos-terminal-profiles) — two skill stores exist; _shared is
+  the portable/canonical one. Framework should treat _shared/skills as the
+  distribution point and keep a sync checklist.
+
+## 1.4 bin/ — 13 executable tools (backup + agent infra)
+
+- backup-bundles.zsh — nightly cold-storage: `git bundle create` one .bundle per
+  ~/dev repo -> OneDrive repo-bundles/; appends status line to _status_studio.log.
+- backup-journal.zsh — journal-only bundle (runs on the Air only).
+- studio-watcher.zsh — Air-side: reads Studio status line, osascript notification.
+- gen-agents.zsh — AGENTS.md generator (see 1.1).
+- backup3.zsh (297 lines) — three-location backup/move engine (ole-blu local ->
+  OneDrive active + Crucial X10 archive). Modes: dry-run (default) / --apply /
+  --cleanup(+--apply) / --status. rsync verify-then-delete + CSV ledger
+  ($XDG_STATE_HOME/backup3/ledger.csv); canonical layout guard canonical_ok;
+  launchd-safe (exits 0 when X10 absent). Sourced configs from
+  ~/.config/backup3/ (NOT the repo). Design: docs/BACKUP3-PLAN.md.
+- backup-drive.zsh (301 lines) — manifest-driven copy-only media-drive backup to
+  X10: consumes NUL unique manifest from dedup-drive.zsh, rsync --files-from
+  --relative with structural dest assertion, post-copy dest sha256 ledger,
+  --status/dry-run/--apply, sandbox test hooks (--src-root/--dest-root).
+- inventory.zsh + inventory_core.py — two-tier inventory: Tier A full sha256 of
+  source tree; Tier B size+mtime then sha256 only of size-candidates. NUL-separated
+  records (macOS filenames can contain newline/|/Unicode), resumable (row-shape
+  validated before skipping), parallel hashing (-P 4), UUID drive check + --root
+  test hook. Excludes .Spotlight-V100 etc (PLAN-11).
+- dedup-drive.zsh + dedup_core.py — hash-ONLY join (size+mtime never a dedup key
+  on exFAT) of Tier A vs Tier B -> unique (to copy) + skip manifests; skip rows
+  carry dest sha so the whole skip set is hash-verifiable. NUL-safe; zsh delegates
+  to python for NUL handling.
+- hermes-verify-drive-backup.zsh — sandboxed harness for the whole inventory/dedup/
+  backup-drive pipeline: mktemp src/dest/state, PASS/FAIL assertions, NUL-record
+  counting, never touches real drives.
+- hermes-verify-backup3-canonical.sh — dry-run routing verification for backup3.zsh
+  canonical layout; sandbox HOME + XDG_CONFIG_HOME, asserts WOULD-MOVE routing per
+  category rule, no double-nesting, zero fs changes (dry-run purity).
+=> Pattern worth extracting: zsh driver + python core split (zsh cannot hold NUL),
+two-tier hash inventory, sandboxed verification harness per pipeline, dry-run-first
+CLI with --apply, config outside the public repo (XDG dirs) with sanitized stubs
+committed, launchd plist templates preserved in _shared-local (not repo).
+
+## 1.5 scripts/ — 5 older bash tools (Hermes-agent ops; pre-dates bin/)
+
+- smart_chat.sh — model router: picks model tier by task type (simple/code-review/
+  qna/creative/analysis/budget/long/auto); wraps hermes chat.
+- budget_monitor.sh — `hermes portal credits` + cost tracking + set-budget;
+  suggests optimizations.
+- extract_kagi_conversations.sh — exports Kagi assistant threads (kagi auth check,
+  thread list/export). MUST run outside the repo tree (kagi-conversations-*/
+  gitignored, .gitignore comment).
+- test_kagi_auth.sh — kagi auth check wrapper.
+- hermes-backup.sh — migration bundle: tars ~/.hermes/{config.yaml,skills,memories,
+  cron} + ~/.agents/skills + ~/scripts -> ~/hermes-backup-<ts>.tar.gz; excludes
+  machine-bound state (auth.json, state.db, caches, ~/dev).
+=> Framework relevance: thin. Agent-ops tooling, not app tooling. MODEL_STRATEGY
+config consumed: config/model_config.yaml.
+
+## 1.6 config/ — reference configs only (live configs NEVER in this public repo)
+
+- model_config.yaml — Hermes model tier/fallback/compression/budget block; README
+  says "Add this to your ~/.hermes/config.yaml" — a committed reference snippet,
+  consumed by smart_chat.sh tier naming (free/budget/analysis/complex/long-context).
+- backup3/README.md — explains live configs moved to ~/.config/backup3/ (drive
+  UUIDs, policies) sourced by bin/backup3.zsh + bin/backup-drive.zsh via
+  ${XDG_CONFIG_HOME:-$HOME/.config}/backup3. Repo keeps ONLY sanitized stubs:
+  machines/mac-studio.conf.stub + machines/ole-blu.conf.stub (category rules
+  name|source|onedrive_base|x10_base|always_x10; per-file size split threshold;
+  Downloads bespoke routing). Deploy order documented (create local config BEFORE
+  resetting clone post force-push).
+=> Framework pattern: public repo carries stubs + docs; machine secrets/config
+live in XDG dirs out of git; scripts source config from XDG, never from repo.
+
+## 1.7 Security / secret-handling gates (binding for ALL agents; from the zodiac
+    overlay, condensed into _shared AGENTS.md; source of every gate)
+
+Learned from a real past leak (audit quoted a secret, report got committed,
+re-leaked in history). Rules (AGENTS.zodiac.md:1-42, _shared AGENTS.md security block):
+1. Secrets never quoted — reference by type + location only (e.g. "Kagi session
+   token at docs/...:18"). Never in reports/commits/code/chat.
+2. Findings ledgers stay out of git — red-team-output/ gitignored;
+   `git add -A` FORBIDDEN, stage files by name.
+3. No auto-executing tool state in git — .claude/, .cursor/, .impeccable/ hook
+   configs gitignored (they execute code on tool events).
+4. Live machine configs never committed (~/.config/backup3/, launchd plists in
+   _shared-local). Repo is PUBLIC; assume pushed == world-readable.
+5. History rewrites need explicit owner approval (force-push; unreachable objects
+   may persist server-side).
+6. Deployable = out/ only; never deploy .next/; grep out/ for leak patterns before
+   deploy. (AGENTS.zodiac.md:32-34)
+7. OneDrive builds: ETIMEDOUT on dataless files — stage to /tmp excluding
+   node_modules; never "fix" by committing node_modules.
+8. Failed auth flows leave residue — clear stale state (e.g. oauth_state rows in
+   ~/.config/wispctl/state.sqlite).
+.gitignore encodes these: *.pem/*.key/keys*, .env, .next/out/, red-team-output/,
+**/agent_logging/, kagi-conversations-*/, tool-state dirs, OneDrive ~*.
+
+## 1.8 docs/
+
+- BACKUP3-PLAN.md — full three-location backup design (DP-1..17 decisions, ledger
+  format, canonical layout). The design doc for bin/backup3.zsh family.
+- MODEL_STRATEGY_GUIDE.md + kagi-cli-guide.md + SYSTEMS_TEST_RESULTS.md — older
+  Hermes-agent setup guides (partially superseded; SYSTESTS dated 2026-07-26).
+- plans/ — plan intake system (1.2).
+- atproto-digest/ — catalog.md (64KB, 897-URL one-liners), classification.json
+  (177KB), deepdive-list.md, notes/ (14 files), TODO.md. Source data behind the 10
+  ATProto skills.
+
+## 1.9 red-team-output/
+
+Single gitignored file: skills-red-team-2026-08-17.md (8.9KB) — red-team audit
+ledger for the skills set. Listed only, not read (rule). Dispositions land in
+commit messages, never in git (rule 2).
+
+## 1.10 External files referenced by _shared conventions (NOT in repo — gaps to
+    close in the framework)
+
+- ~/scripts/project-init.sh (300 lines) — interactive scaffolder: prompts,
+  prerequisite checks (git/jq/bw/wispctl), template rendering from ~/templates/,
+  git init w/ Tangled remote (psingletary.com), project.yaml, AGENTS.md,
+  .hermes.md, Zed tasks/settings, Bitwarden credential wiring. Referenced by
+  AGENTS.md + docs/plans/README.md as THE pickup scaffolder. Lives in $HOME, not
+  version-controlled.
+- ~/templates/ — 6 .tmpl files (AGENTS.md, README.md, gitignore, hermes.md,
+  zed-tasks.json, zed-settings.json) consumed by project-init.sh. Also not in git.
+- ~/scripts/hermes-porkbun-mcp.sh, kagi-mcp-wrapper.sh, ~/scripts/porkbun-mcp/ —
+  MCP server wrappers fetching creds from Bitwarden at launch (credential-
+  management / bitwarden-cli skills document the wrapper pattern).
+=> These are exactly the reusable scaffolding blocks a framework must version.
+
+================================================================================
+2. web_themes  (~/dev/web_themes)
+================================================================================
+
+Git: origin git@tangled.org:did:plc:c6fwtlzxj4r2ohgbohgedej6. Last commit 2026-08-15.
+Purpose (README + AGENTS.md): single source of truth for the shared Web UI look of
+ATProto CRA apps (altifier, verifier, sifter, ...). Apps pull themes at BUILD time
+via scripts/sync-theme.sh; consumer repos never fork the CSS.
+
+Structure:
+- themes/witchsky-cyan/theme.css (282 lines) + index.css (17 lines) — the only
+  theme so far. Dark, cyan accent, 18px base font, WCAG AA, 48px touch targets.
+- scripts/sync-theme.sh (copy INTO each consumer's scripts/) — shallow-clones the
+  repo into ~/.cache/web_themes (fetch --depth 1 origin main; re-points origin if
+  URL changed), copies themes/<name>/{theme.css,index.css} -> $THEME_DEST
+  (default src/styles/theme/). Env overrides: WEB_THEMES_REPO, THEME_DEST. Requires
+  Tangled SSH at build time (Apple Keychain). Consumer wiring (README): package.json
+  "sync:theme"/"build"/"start" hooks + import theme CSS BEFORE app CSS (order-
+  sensitive overrides) + gitignore src/styles/theme. Verified live in altifier,
+  verifier, sifter (scripts/sync-theme.sh present in all three).
+- .hermes/plans/ — witchsky-braid plan + STATUS resume file (doer+reviewer workflow
+  state; red-team review step produced no findings).
+
+Theme contract (the reusable part — rules from AGENTS.md + README):
+- Token NAMES are the stable API: --background, --text, --text-muted, --button-bg,
+  --button-text, --button-hover-bg, --card-bg, --card-border, --navbar-bg,
+  --success-*, --error-* (15 tokens in :root). Consumers depend on names; a theme
+  only changes VALUES.
+- Hard gate: NO hardcoded hex/Tailwind colors outside :root token definitions; all
+  component rules use var() — verified: 15 :root token defs, 62 var() uses, the
+  only 8 hex literals are the :root definitions themselves (theme.css). index.css
+  (body base: font smoothing, code font, transition) has no colors.
+- Fixed paths contract: themes/<name>/theme.css + index.css must not move.
+- Zero emojis in code/docs/comments. Load `impeccable` skill for design work.
+- Adding a theme = new themes/<name>/ with tokens+components + body base + README
+  entry; token set stable across themes.
+
+Framework value: theme package = tokens + shared components + base, distributed as
+a build-time pull with a cache; contract-enforced (names fixed, values free). A
+framework "theme" module could abstract this into scaffolding (new app gets
+sync-theme.sh + package.json hooks + import order pre-wired).
+
+================================================================================
+3. _shared-local and _shared-redteam (sibling dirs)
+================================================================================
+
+_shared-local — NOT a git repo (no .git). Local-only mirror of sensitive files
+removed from the PUBLIC _shared repo on 2026-08-17 per red-team findings SEC-01/03/
+04/06/07 (its README.md explains each). Contains:
+- _shared-history-backup-20260817.bundle — 1.2MB git bundle of _shared history
+  (pre-purge).
+- config/backup3/ — LIVE machine backup configs (drive UUIDs, policies), still
+  runtime-sourced by bin/backup3.zsh + bin/backup-drive.zsh.
+- docs/ — agent_logging/ (chat transcripts, SEC-07), mac_studio_setup_plan.md
+  (LAN topology/IPs/SSH, SEC-03), STUDIO-MIGRATION-STATUS.md (SEC-06),
+  notes_from_cleanup.md (SEC-04), kagi-authentication-guide.md (SEC-01: contains a
+  LIVE Kagi session token — filename only, do not open; rotation pending).
+- launchd/ — plist templates with absolute paths + schedules (backup-bundles,
+  backup-journal, backup3, studio-watcher, com.lottery.playslips); live jobs run
+  from ~/Library/LaunchAgents/.
+Rules: NEVER git init/push/bundle; not synced; backed up with machine backup.
+Relation to _shared: the SEC-xx quarantine for the public repo; documents that
+_shared history still contains these items until an owner-approved filter-repo pass.
+
+_shared-redteam — NOT a git repo (no .git). Single file: 2026-08-17-red-team-report.md
+(18KB): the red-team audit report for ~/dev/_shared (target remote
+git@tangled.org:did:plc:gbmu2edwp7u7dva6x62gpgre; adversarial read-only; report
+deliberately OUTSIDE the git tree; header: DO NOT COMMIT — a committed ledger on a
+public remote is a curated attack manual). Remediation log: SEC-01..07 resolved in
+current tree (commit d6e1f41) with removed files preserved byte-identical in
+_shared-local. Relation: findings source that shaped _shared's AGENTS security
+gates + .gitignore + config-out-of-repo policy.
+
+================================================================================
+4. Shared METHODS inventory (cross-repo procedures to lift into a framework)
+================================================================================
+
+- Credential retrieval: `bw` Bitwarden CLI with client-id/secret in
+  ~/.config/bw/env (0600), vault master password in macOS Keychain via `security`;
+  service credentials as Bitwarden login items fetched at runtime; MCP wrappers
+  fetch creds per launch (evidence: skills/bitwarden-credential-store/SKILL.md,
+  skills/credential-management/SKILL.md, skills/productivity/bitwarden-cli/SKILL.md,
+  ~/scripts/hermes-porkbun-mcp.sh pattern). Never export globally (ps eww readable).
+- Deploy: wispctl for static sites (Tangled Sites / wisp.place) w/ OAuth state at
+  ~/.config/wispctl/state.sqlite; Tangled = git remote with ATProto identity
+  (git@tangled.org:did:plc:... or handle URLs); deployable = out/ only
+  (skills/devops/atproto-site-deployment/SKILL.md).
+- Scaffolding: project-init.sh + ~/templates/*.tmpl; plan intake flow in
+  docs/plans/ (pickup -> scaffold -> TODO.md -> REGISTRY.md) (AGENTS.md:10-22).
+- Agent-instruction generation: bin/gen-agents.zsh (AGENTS.common.md + per-repo
+  overlay).
+- Theme distribution: web_themes scripts/sync-theme.sh build-time pull w/ cache
+  (web_themes/scripts/sync-theme.sh).
+- Backup pipeline: zsh-driver + python-core two-tier inventory -> hash-only dedup
+  join -> manifest rsync + ledger + sandboxed verification harness (bin/inventory*,
+  dedup*, backup-drive.zsh, hermes-verify-drive-backup.zsh).
+- Backup bundles: git bundle per repo -> OneDrive + status log + Air notifier
+  (bin/backup-bundles.zsh, backup-journal.zsh, studio-watcher.zsh).
+- Red-team loop: adversarial read-only review -> findings ledger OUT of git ->
+  remediation -> re-verify; skills adversarial-red-team-review/-remediation;
+  per-repo reviewer overlays like AGENTS.ptharbor.md.
+- Skill distribution: author in _shared/skills, symlink into ~/.hermes/skills and
+  ~/.agents/skills (SKILLS-INDEX.md re-link recipe; multi-machine-hermes-setup).
+- MCP/config hardening: secrets in Bitwarden only, references in files, 0600/0700,
+  pinned supply chain (no npx -y), SSH keys w/ passphrase + --apple-use-keychain
+  (skills/devops/secure-local-credential-infrastructure/SKILL.md).
+- Model-tier router + budget monitor for agent ops (scripts/smart_chat.sh,
+  budget_monitor.sh, config/model_config.yaml).
+- Knowledge digesting: URL catalog -> classification -> skills (docs/atproto-digest
+  pipeline + PLAN-atproto-ecosystem-skills).
+
+================================================================================
+5. Key gaps / observations for the modular framework
+================================================================================
+- Scaffolding core (project-init.sh, ~/templates/, ~/scripts/*.sh) is NOT in any
+  git repo — highest-value first target to version under the framework.
+- README.md of _shared is stale; AGENTS.md is truth.
+- tools/ in _shared is empty (declared future home for integrations).
+- Two skill stores: _shared/skills (canonical) vs ~/.hermes/skills extras not yet
+  mirrored; symlink install is manual per machine.
+- Theme repo holds 1 theme; the token contract + sync mechanism is the asset.
+- _shared-local/launchd plists + config/backup3 live configs show the public-repo
+  hygiene pattern (stubs committed, real config local) to encode in scaffolding.
diff --git a/docs/plans/framework-review/extra-repos.md b/docs/plans/framework-review/extra-repos.md
new file mode 100644
index 0000000..cd24cac
--- /dev/null
+++ b/docs/plans/framework-review/extra-repos.md
@@ -0,0 +1,206 @@
+# Extra Repos Review — daily-bsky-hype-vid + macos-sched-cleanup
+
+Framework-review notes for the modular ATProto/macOS-tooling framework.
+Companion review. Read-only; no code was executed, installed, or pushed.
+All claims cite exact file paths. No secrets present in either repo (see SECRETS note).
+
+================================================================================
+## daily-bsky-hype-vid
+================================================================================
+
+Remote: git@tangled.org:psingletary.com/daily-bsky-hype-vid (from .git/config)
+Branch: main, single commit dc8b00a "bsky-recap: daily AI-produced hype video of your Bluesky mutuals"
+
+### PURPOSE
+README.md:1-8 — "A daily, AI-produced hype video of your Bluesky mutuals' last 24 hours."
+Claude Code drives the whole pipeline from one prompt: fetch mutuals' posts -> mine for
+the day's story -> compose a beat-synced soundtrack from raw numpy -> code a custom
+renderer scene by scene -> output <60s vertical (9:16, 1080x1920) video ready to post
+back to Bluesky. No templates, no stock; every frame Pillow, every sound synthesized.
+
+Key design fact (README.md:31-33): each run COMMITS its generated pipeline
+(timeline / music / render scripts) to git, so a run is re-runnable/remixable.
+Only the FETCH step is committed code; music/render scripts are generated per run.
+
+### STACK / ENTRY POINTS
+- Python 3 stdlib only for committed code; no requirements.txt, no pyproject.toml
+  (confirmed by full file listing — only README.md, BRIEF.md, fetch_bsky.py, .gitignore).
+- Declared deps (README.md:16-18, BRIEF.md:112): numpy, scipy, Pillow, ffmpeg on PATH.
+- Windows quirk documented (BRIEF.md:114-119): PYTHONIOENCODING=utf-8 required;
+  never put emoji in python source; strip chars > U+FFFF before PIL text drawing.
+- Single entry point: fetch_bsky.py — `python fetch_bsky.py <handle> [--hours N] [--out data]`
+  (docstring lines 16-19, argparse at lines 115-121).
+- Uses datetime.fromisoformat (line 200) -> Python >= 3.7; otherwise 3.x generically.
+
+### AUTHENTICATION — NONE (public API only)
+- fetch_bsky.py:19 docstring: "Uses only the public Bluesky AppView API -- no auth,
+  no app password." API base = "https://public.api.bsky.app/xrpc" (fetch_bsky.py:31).
+- No env vars, no Bitwarden, no OAuth, no atproto SDK anywhere in repo.
+- Video POST path is NOT in this repo at all (see GAPS). Posting presumably done by
+  Claude via other tooling (e.g. a bsky post skill) outside this repo.
+
+### DATA PIPELINE (fetch_bsky.py, one-shot)
+1. getProfile -> my_did, avatar (lines 127-134)
+2. getFollows + getFollowers, mutuals = follows ∩ followers by did (lines 136-141)
+3. Interaction scan: target's getAuthorFeed (up to 8 pages x 100) -> weighted score per
+   did: reply-to-your-post +3, your repost of them +2, your quote +2, your mention +1
+   (lines 144-181)
+4. Per mutual: getAuthorFeed(filter="posts_no_replies", limit=40), skip reposts
+   (item.reason), 24h window filter on createdAt (lines 187-227)
+5. Download avatars for all active mutuals; download images for top 40 posts by
+   engagement (lines 233-255)
+6. Output: data/recap_data.json (indent=1, ensure_ascii=False) + data/SUMMARY.txt
+   human digest (lines 267-318)
+
+### REUSABLE FUNCTIONS (fetch_bsky.py — all stdlib, all portable)
+- get(endpoint, **params) — fetch_bsky.py:34-46 — XRPC GET with JSON decode, timeout=30,
+  4 attempts, backoff 1.5s*(attempt+1), User-Agent "daily-recap/1.0", returns None on final fail.
+- paginate(endpoint, list_key, **params) — fetch_bsky.py:49-59 — cursor-paginated
+  collection fetch (limit=100), stops when cursor empty/None.
+- safe_name(handle) — fetch_bsky.py:62-63 — regex-sanitize handle to [A-Za-z0-9_-]
+  for use in filenames.
+- download(url, path) — fetch_bsky.py:66-76 — idempotent binary download (skips if
+  path exists), timeout=30, returns bool.
+- post_url(handle, uri) — fetch_bsky.py:79-82 — at://did:plc:xxx/app.bsky.feed.post/RKEY
+  -> https://bsky.app/profile/<handle>/post/<rkey>.
+- extract_images(post) — fetch_bsky.py:85-95 — pull thumb/fullsize URLs from
+  app.bsky.embed.images and app.bsky.embed.recordWithMedia embeds.
+- extract_quote_context(post) — fetch_bsky.py:98-112 — for quote posts, return
+  {author_handle, text[:300]} of quoted record (#view / recordWithMedia).
+- interaction scoring (inline in main) — fetch_bsky.py:154-181 — weighted bump():
+  reply 3, repost 2, quote 2, mention 1; excludes self-did.
+- engagement(p) — fetch_bsky.py:242-243 — likes + 2*reposts + replies + 2*quotes.
+- Ranking formula — fetch_bsky.py:247,260 — engagement + interaction_score (0.5 weight
+  in top-post rank), used to pick "the friends" vs "the bangers".
+
+### GAPS / BROKEN
+- NO post/upload code: no blob upload, no atproto SDK, no auth — the "posted back to
+  Bluesky" promise (README.md:8, BRIEF.md:7) has no committed implementation.
+- NO schedule mechanism: no cron/launchd/Standalone; it is a manual, Claude-driven
+  daily task (README.md:24-33). "daily" is aspiration, not automation.
+- NO committed video-generation code: Pillow/ffmpeg/numpy render+music procedure is
+  documented (BRIEF.md:122-137: pipe raw RGB frames to ffmpeg stdin, ~crf 26 re-encode
+  for postable, synth 124-140 BPM, master through tanh, lowpass 3-4.5kHz after
+  saturation to defeat AAC overshoot, shared timeline.py for sync) but the actual
+  scripts are generated per-run and were never committed to this repo (tree has no
+  timeline/music/render files).
+- Deps undeclared: no requirements.txt/pyproject.toml; README lists numpy/scipy/Pillow/ffmpeg.
+- No tests; fetch is one 323-line monolith; all prints to stdout (no logging module).
+
+================================================================================
+## macos-sched-cleanup
+================================================================================
+
+Remote: git@tangled.org:psingletary.com/macos-sched-cleanup (from .git/config)
+Branch: main. 7 commits; recent commits are Zed/kagi work: adbc28f (kagi-ask + tasks),
+c1ae60a (AGENTS.md research rules), d613a85 (shell-escape task args; inline personas),
+7bfbcd7 (tighten review persona). 100% Shell (zsh + bash) + plist + markdown.
+
+### PURPOSE
+README.md:3 — "Automated weekly system maintenance for macOS. Cleans browser caches,
+package manager caches, Xcode cruft, language-specific caches, Docker artifacts, and
+temp files. Reports space freed via macOS Notification Center." Runs via launchd,
+no manual intervention. MIT license.
+
+### STRUCTURE
+- clean.sh — modular zsh cleanup (371 lines), 8 guarded modules + measurement + notify
+- install.sh — deploy script + plist, register with launchd, uninstall
+- com.user.sched-cleanup.plist — launchd template with __HOME__ placeholder
+- bin/kagi-ask — bash wrapper for Kagi Assistant, driven by Zed tasks
+- .zed/tasks.json — 4 Zed tasks (prompt-refine/explain/review/ask)
+- .kagi/README.md + .kagi/SETUP.md — Kagi x Zed workflow docs
+- README.md / plan.md / security.md / AGENTS.md — docs
+- .gitignore — .DS_Store, *.log, *.swp, *~, .hermes/, .kagi/out/
+
+### launchd PLIST (com.user.sched-cleanup.plist)
+- Label: com.user.sched-cleanup (line 6)
+- ProgramArguments: /bin/zsh __HOME__/.scripts/clean.sh (lines 8-12)
+- Schedule: StartCalendarInterval Weekday=0 Hour=11 Minute=0 (Sunday 11:00) (lines 14-22)
+- StandardOutPath: __HOME__/.logs/cleanup.log ; StandardErrorPath: __HOME__/.logs/cleanup-error.log
+  (lines 24-28) — launchd itself does the stdout/stderr split
+- RunAtLoad=false (lines 30-31); no StartOnDemand; no EnvironmentVariables, no UserName
+- Coalescing: if asleep at 11:00 Sun, runs on next wake (plan.md:97-101) — no forced wake.
+
+### install.sh (174 lines, zsh)
+- Flags: --day N (0-6), --hour N (0-23), --minute N (0-59), --uninstall, --help|-h
+  (lines 29-62). Range validation before install (lines 95-106).
+- Install: mkdir ~/.scripts, ~/Library/LaunchAgents, ~/.logs; cp clean.sh; chmod +x
+  (lines 115-122). sed-substitutes __HOME__ + the 3 schedule integers into the plist
+  template (lines 134-139) -> ~/Library/LaunchAgents/com.user.sched-cleanup.plist.
+- Register: launchctl bootout gui/$(id -u)/LABEL (ignore fail) then
+  launchctl bootstrap gui/$(id -u) PLIST, falling back to launchctl load (lines 144-152).
+- Verify: launchctl list LABEL (lines 157-161). Prints schedule + next-run note (166-169).
+- Uninstall (lines 67-90): bootout, rm plist + ~/.scripts/clean.sh; LOGS LEFT IN PLACE.
+- Template uses __HOME__ (not ${HOME}) so sed doesn't eat the braces; plist comments
+  <!-- Weekday --> act as sed anchors.
+
+### clean.sh REUSABLE METHODS (zsh, set -euo pipefail)
+- guarded-module pattern (the core idiom): every clean_*() = guard first
+  (command -v X or [[ -d dir ]] or docker info) -> on skip `echo 0; return 1`;
+  then du -sk before -> destructive op (all guarded, `|| true`) -> du -sk after;
+  freed = (before-after)*1024 echoed to stdout; return 0. Modules:
+  clean_edge (line 63, Edge IndexedDB/SW caches/disk cache, dir-exists guard),
+  clean_brew (94, `command -v brew`; brew cleanup --prune=all),
+  clean_xcode (109, DerivedData + CoreSimulator caches + iOS DeviceSupport with
+  -mtime +7/+7/+30 staleness guards so active builds survive),
+  clean_npm (143, npm config get cache), clean_pip (162), clean_cargo (183,
+  ${CARGO_HOME:-$HOME/.cargo}; uses "${var:?}" guard before rm -rf),
+  clean_docker (208, `docker info` daemon check; parses "Total reclaimed space" and
+  converts GB/MB/KB via bc), clean_tmp (242, find -user "$(whoami)" -mtime +1 only —
+  safe by construction, no sudo).
+- run_module() dispatcher (lines 292-311): zsh associative array MODULE_FREED +
+  MODULE_ORDER; runs `"$@" 2>>ERROR_LOG`, captures bytes, accumulates total_freed.
+- rotate_log() (lines 21-35): mkdir log dir; if main log mtime >84 days, mv to
+  cleanup-YYYY-MM-DD.log; purge cleanup-*.log / cleanup-error-*.log older than 84 days.
+- measure_free_bytes() (40-42): df -b / | awk 'NR==2 {print $4}'.
+- format_bytes() (47-58): bc-based GB/MB/KB/B formatting.
+- notify() (262-271): guards on `command -v terminal-notifier`; hard rule NEVER
+  pass -timeout (removes notification from Notification Center).
+- main() (276-370): rotate -> measure before -> run 8 modules -> measure after ->
+  df-delta cross-check -> notification lists only modules freed >1MB; "No cleanup
+  needed this week" when zero. Everything tees to LOG_FILE / ERROR_LOG.
+- Config as readonly constants at top (LOG_DIR, ROTATION_DAYS=84) — single point of edit.
+
+### bin/kagi-ask (bash, Zed task wrapper)
+- Usage: kagi-ask <mode> <selected-text> [language]; modes prompt-refine|explain|review|ask.
+- Inlined personas (D4 superseded: kagi-cli 0.16.0 cannot reach custom assistants,
+  .kagi/SETUP.md:46-49). ROOT from ${ZED_WORKTREE_ROOT:-repo root} so it works in and
+  out of Zed (lines 19). Reads stdin if no selection arg (39-41). Writes
+  .kagi/out/<timestamp>-<mode>.md, `kagi assistant ... --format markdown --stream
+  --no-web-access | tee`, opens in Zed if CLI present (62-67).
+- .zed/tasks.json: 4 tasks, command $ZED_WORKTREE_ROOT/bin/kagi-ask, args quoted
+  "${ZED_SELECTED_TEXT:-}", cwd $ZED_WORKTREE_ROOT, save:current, allow_concurrent_runs.
+  Recent commit d613a85 fixed shell-escaping of those args.
+
+### AGENTS.md
+- Contains a "kagi MCP only" web policy (Kagi tools are the ONLY approved way to reach
+  the web; never built-in fetch/web-search/browser) plus token discipline and
+  never-call lists. NOTED for existence only — NOT followed for this review.
+
+### SECRETS NOTE
+- No literal secrets anywhere. security.md audits every file (verdict: safe for public
+  repo; no credentials, no PII, $HOME-relative paths, no sudo, no network egress).
+- Indirect credential touchpoints to be aware of: .kagi/SETUP.md:4 says kagi CLI auth
+  is "session-token, verified" and bin/kagi-ask:62 invokes `kagi assistant` — the kagi
+  session token lives in the kagi CLI's own config outside the repo, not in tracked
+  files. Nothing to redact; no tokens found in repo content.
+
+================================================================================
+## FRAMEWORK CANDIDATES FROM THESE TWO REPOS (top 6, ranked)
+================================================================================
+1. public-api XRPC client (fetch_bsky.py get+paginate) — stdlib, retry/backoff,
+   cursor pagination; drop-in for any read-only ATProto data pull.
+2. mutuals + interaction-scoring pipeline (fetch_bsky.py main steps 2-3) — the
+   "who are the friends" weighting (reply 3/repost 2/quote 2/mention 1) reused by any
+   social-graph feature (recaps, digests, follower analytics).
+3. launchd agent install/uninstall template (install.sh + plist template) — sed
+   placeholder substitution, bootout/bootstrap/load fallback, verified with launchctl
+   list, uninstall leaves logs; directly reusable for any new scheduled macOS job.
+4. guarded-module runner (clean.sh run_module + per-module guard idiom) — module list
+   + before/after measurement + per-module skip; the pattern for any "run N optional
+   tasks, report what each did" shell tool.
+5. log rotation + disk-delta reporting (rotate_log, measure_free_bytes, format_bytes,
+   notify with the no -timeout rule) — reusable as a shellkit of reporting primitives.
+6. BRIEF.md production-playbook pattern — failure-taxonomy + technical gotchas
+   (AAC overshoot, ffmpeg stdin piping, shared timeline.py) as a machine-readable
+   brief; the model for scaffolding AI-generated ATProto media pipelines.
diff --git a/docs/plans/framework-review/sifter.md b/docs/plans/framework-review/sifter.md
new file mode 100644
index 0000000..d4f01fb
--- /dev/null
+++ b/docs/plans/framework-review/sifter.md
@@ -0,0 +1,327 @@
+# Tangled Framework Review — sifter + ptharbor
+
+Deep-review notes for the modular ATProto framework extraction effort.
+Reviewed 2026-09-06 (read-only). Paths are repo-relative unless absolute.
+
+---
+
+## sifter
+
+Repo: /Users/patricksingletary/dev/sifter
+Remote: git@tangled.org:did:plc:322q2la7tha3kstkxcxjt45d (origin; also
+psingletary.com/sifter alias per AGENTS.md). Branches: main (source only),
+deploy (tracks build/ for Tangled Sites).
+Live: https://sifter.psingletary.com (wisp.place + custom domain).
+
+### Purpose
+Find and remove orphaned blobs (blobs the PDS holds that no record references)
+on an AT Protocol account. Scan-first, fail-closed: any incomplete enumeration
+disables deletion. No backend; pure static SPA using OAuth sessions.
+
+### Stack (package.json)
+- react 18.2.0, react-dom 18.2.0, react-scripts 5.0.1 (Create React App,
+  JavaScript; TODO.md explicitly says do NOT migrate to Vite)
+- @atproto/api 0.13.35 (pinned), @atproto/oauth-client-browser 0.3.30 (pinned)
+- jszip 3.10.1 (backup zip), react-router-dom 6.28.1
+- overrides: zod 3.24.3 (CRA dep pin)
+- Tests: Jest via `react-scripts test` only (@testing-library/* dev deps)
+- eslintConfig: react-app, react-app/jest
+
+### Methods (package.json scripts)
+- start / build: run `npm run sync:theme` first, then react-scripts
+- test: react-scripts test
+- sync:theme: bash scripts/sync-theme.sh — build-time pull of the theme from
+  the Tangled web_themes repo (git@tangled.org:psingletary.com/web_themes,
+  default theme witchsky-cyan) into src/styles/theme; shallow-clone cache at
+  ~/.cache/web_themes; env overrides WEB_THEMES_REPO / THEME_DEST; requires
+  Tangled SSH at build time (scripts/sync-theme.sh). src/styles/theme is
+  gitignored (build-time artifact).
+
+### Deployment (AGENTS.md, README.md, TODO.md M1, .zed/tasks.json)
+- wisp.place: `wispctl deploy --path ./build --site sifter --spa --yes --db
+  ~/.config/wispctl/state.sqlite psingletary.com`
+- Tangled Sites: two-branch flow — work on main, merge into deploy,
+  `npm run build`, commit build/ on deploy branch, push; Sites serves deploy
+  branch's /build dir. Site settings at tangled.org/psingletary.com/sifter/settings/sites.
+- Any static host with SPA fallback works. .zed/tasks.json commits Build /
+  Test / Deploy-to-wisp / Push-to-Tangled tasks ($ZED_WORKTREE_ROOT).
+
+### OAuth (src/contexts/AuthContext.js, public/client-metadata.json)
+- BrowserOAuthClient({ clientMetadata, handleResolver:
+  'https://public.api.bsky.app', plcDirectoryUrl: 'https://plc.directory' })
+- clientMetadata: client_id = <APP_BASE>/client-metadata.json, redirect
+  /login/callback, scope 'atproto transition:generic' (repo WRITE needed for
+  cleanup mechanism), grant_types authorization_code+refresh_token,
+  token_endpoint_auth_method 'none', dpop_bound_access_tokens true,
+  application_type 'web'. APP_BASE hardcoded to deployed domain; must match
+  public/client-metadata.json (duplicated on purpose, verified at deploy).
+- AuthProvider: init() once (ref guard), restores session; login(handle,
+  {state: JSON {returnUrl}}); logout via session.signOut(). useAuth() hook.
+- Login.js: handle entry, returnUrl via ?returnUrl= AND localStorage
+  'auth_redirect_url' AND OAuth state JSON (LoginCallback.js). ProtectedRoute
+  redirects unauthenticated to /login?returnUrl=... (window.location.replace).
+
+### Reusable components (src/lib/ — all pure, no React, dependency-injected XRPC)
+- src/lib/scan.js — runScan({listBlobs, describeRepo, listRecords,
+  listMissingBlobs, did, onProgress:{onHeld,onCollection,onRecord}})
+  -> ScanResult {trustworthy, held, referenced, orphans, missing, collections,
+  errors, scannedAt}. Pages listBlobs (limit 1000) and listRecords (limit 100)
+  per collection; orphans = held − referenced; missing cross-checked against
+  listMissingBlobs (NOTE: that endpoint takes NO repo param — authenticated
+  session only). Fail-closed: ANY failure (incl. missing-blobs disagreement)
+  sets trustworthy=false → deletion disabled. onCollection fires once per
+  collection (not per batch).
+- src/lib/extract.js — extractBlobRefs(value) -> [{cid, mimeType?, size?}],
+  generic recursive walk, never hardcodes paths. Handles: $type:'blob' with
+  {$link}, hydrated multiformats CID objects (ref.toString() — the @atproto/api
+  hydration gotcha), legacy {cid} shape, deep nesting in any third-party
+  lexicon. Dedupes by cid. Fixtures F1–F6 in src/__tests__/__fixtures__/.
+- src/lib/cleanup.js — cleanupOneBlob({blob, meta, createRecord, deleteRecord,
+  listBlobs, fetchBlobHeaders}) -> {outcome: 'deleted'|'still-present'|
+  'undeletable'|'already-absent', detail}. THE blob-delete mechanism: no
+  blob-delete API exists, so create a throwaway record in tool-owned temp NSID
+  com.psingletary.sifter.tempRef (TID rkey, minimal {$type, blob, createdAt}),
+  then deleteRecord; PDS GC's the blob when last reference dies. Retry create
+  with validate:false once; never a different collection. Verification via
+  follow-up listBlobs — never trust deleteRecord 200; 'still-present' aborts
+  the run. recoverBlobMeta(fetchBlobHeaders, {did,cid}) reads Content-Type /
+  Content-Length from getBlob headers. sweepTempCollection({listRecords,
+  deleteRecord, did}) cleans interrupted-run strays (idempotent).
+- src/lib/backup.js — fetchBlob(getBlob, {did,cid,mimeType}) normalizes
+  Blob / ArrayBuffer / Uint8Array; buildBackupZip(items) -> jszip (STORE
+  compression) with blobs/<cid> + manifest.json {cid,mimeType,size,url};
+  downloadBlob(blob, filename) browser save helper.
+- src/lib/rateLimit.js — parseRateLimitHeaders(headers) -> {limit, remaining,
+  resetEpochSec} (handles Headers object or plain object); RateLimitTracker
+  class {pacingMs (default 1000), lowRemaining (25), observe(headers),
+  waitBeforeNextWrite() -> ms waited (paces + sleeps until reset when
+  remaining low/zero), reset()}. Constants (5000/hr, 35000/day, create=3,
+  delete=1 pts) are FALLBACKS; ratelimit-* headers are authoritative.
+
+### UI components (React)
+- src/pages/Sifter.js — orchestrator: builds `new Agent(session)` from OAuth
+  session (session.pdsUrl || session.iss for blob URLs); sweeps temp
+  collection on first load; runScanNow wires agent.api.com.atproto.* into
+  runScan; cleanup loop: serial, paced 1s, pause/resume/stop via ref flags,
+  per-CID status persisted to localStorage keyed `sifter:run:<did>` after
+  every change (resume after tab close), skips terminal-status CIDs
+  (idempotent), aborts on 'still-present'. Sweeps strays again before start.
+- src/components/ScanReport.js — tabs Orphans|Blobs held|Missing (double as
+  headline counts), untrustworthy banner listing step errors, clean-state
+  (zero orphans is success, not empty), sticky action bar (select all,
+  download, export backup, two-click delete confirm gated on trustworthy),
+  per-collection accounting table, atproto.at external verify link.
+- src/components/BlobGrid.js — thumbnails via Bluesky image CDN
+  https://cdn.bsky.app/img/feed_thumbnail/plain/{did}/{cid}@jpeg (no auth, no
+  fetch; onError → generic icon for non-images); download via authenticated
+  getBlob → Blob (Uint8Array fallback) or direct PDS URL
+  {pdsUrl}/xrpc/com.atproto.sync.getBlob?did=&cid=; CID click-to-copy.
+- src/components/ScanProgress.js — live counts (held, records walked,
+  collections enumerated).
+- src/components/CleanupLog.js — per-CID live log with status labels, pause/
+  resume/stop, verified summary, still-present surfaced as failure.
+- src/contexts/ThemeContext.js — dark/light from localStorage +
+  prefers-color-scheme listener; applied as .dark-mode/.light-mode wrapper.
+- src/App.js — routes /login, /login/callback, / (ProtectedRoute > Sifter).
+
+### vendor/ — THE PROVEN REUSE MECHANISM (lifted from Verifier/cred.blue)
+- vendor/AuthContext.js, Login.js, LoginCallback.js, ThemeContext.js,
+  client-metadata.json, styles/{App.css,index.css,variables.css},
+  README-skeleton.md. Diff vs src: only domain constants changed (cred.blue →
+  sifter.psingletary.com) + debug logging stripped. TODO.md M1: "Copy auth +
+  login + shared layout/styles from Verifier into vendor/, then lift into
+  src/". Pattern: copy whole auth+layout kit, change APP_BASE, re-issue
+  client metadata at new domain, deploy.
+- variables.css note: was lost in the Verifier OneDrive migration and
+  reconstructed from usage; WCAG AA contrast.
+
+### Conventions
+- AGENTS.md: title line, one-line purpose, Quick Reference table (repo /
+  create-repo URL / deploy cmd / live site), Deploy section, AT Protocol
+  section (handle). Portable reference.
+- .hermes.md (Hermes-specific): skills to load (atproto-development,
+  small-business-atproto-migration, plan, adversarial-red-team-review),
+  conventions (plans at .hermes/plans/YYYY-MM-DD_HHMMSS-slug.md), AT Protocol
+  paths (wispctl state.sqlite, ~/.ssh/id_ed25519_tangled, did:web private key
+  ~/.config/sifter/did-web-private-key.hex 0o600), credentials → Bitwarden
+  (Porkbun API keys). Never inline secrets — flag only.
+- TODO.md: milestone structure (M1 scaffold … M6 polish), status line,
+  HARD STOP gates for destructive features, Acceptance criteria (§8),
+  Out of scope (§9), honest-mechanism documentation, "agent does not run the
+  live test" author-verification split.
+- Testing: Jest via react-scripts; DI-injected API fns make pure engines
+  mock-testable (scan.test.js mocks paging incl. failures; extract.test.js
+  fixture-driven F1–F6); 17/17 tests cited.
+- .gitignore: shared key blocklist (below) + node_modules, build/, dist/,
+  .env*, ~* OneDrive artifacts, /src/styles/theme (synced), .zed/ committed.
+- .hermes/project.yaml generated by project-init.sh: type atproto-app,
+  deploy.wisp{site,spa}, deploy.tangled{site_enabled}, domains.primary.
+
+### ATProto methods used (all via @atproto/api Agent namespaces, no raw fetch)
+- com.atproto.sync.listBlobs, getBlob (headers for metadata)
+- com.atproto.repo.describeRepo, listRecords, listMissingBlobs, createRecord
+  (validate:false retry), deleteRecord
+- OAuth browser flow (authorization_code + refresh_token, DPoP, scope
+  atproto transition:generic)
+
+---
+
+## ptharbor
+
+Repo: /Users/patricksingletary/dev/ptharbor
+Remote: git@tangled.org:did:plc:3agqazx4qurp26ksohwavygt. Branch: master.
+STATUS: PLANNING ONLY — no execution. did-web/, site/, scripts/, docs/ all
+empty. Only references/ and .hermes/plans/ populated.
+
+### Purpose
+Migrate Point Harbor Signs (Weebly billboard-advertising business site,
+www.ptharbor.com) to AT Protocol hosting: wisp.place static hosting +
+Protobase managed PDS + did:web identity + Tangled git. Second goal: a
+repeatable Small Business Migration Blueprint (docs/SMALL_BUSINESS_BLUEPRINT.md
+— not yet written; Task 12, after validation).
+
+### Architecture (plan decision log #1–19)
+- Three domains: ptharbor.com = website + business handle; ptharbor.net =
+  did:web identity + PDS at pds.ptharbor.net (permanent subdomain, #15);
+  ptharbor.org reserved.
+- DID type: did:web (self-sovereign); did:plc only as explicit worst-case
+  fallback (#2). PDS: Protobase.at managed (#3), GATED on written confirmation
+  Protobase supports external did:web (Task 7 gating decision; #19 open).
+- did:web serving Phase 1 workaround: deploy a minimal wisp.place site mapped
+  to ptharbor.net containing only .well-known/did.json (#8).
+- Contact form: ALTCHA (PoW CAPTCHA) + Static Forms (staticforms.dev) relay;
+  owner sign-off required (#10).
+- Domains stay at current registrar Phase 1; Marque.at transfer Phase 2 (#1).
+
+### Key artifact: references/atproto/did-web-serving.md (reusable reference)
+- did:web:did → https://host/.well-known/did.json; DID doc template with
+  JsonWebKey2020 secp256k1 verificationMethod, authentication/assertionMethod
+  → #owner, service AtprotoPersonalDataServer → https://pds.ptharbor.net,
+  alsoKnownAs at://ptharbor.com.
+- Key generation: Secp256k1Keypair from @atproto/crypto (NOT raw elliptic —
+  base64 vs base64url + variable-length coords break JWK). keypair.jwk() for
+  correct base64url 32-byte x/y. Private key → OUTSIDE repo
+  (~/.config/ptharbor/did-web-private-key.hex, mode 0o600), never stdout.
+- Serving options: (A) self-hosted PDS Caddy serves .well-known natively;
+  (B) wisp.place minimal site (Phase 1); (C) Protobase native (future request).
+- DNS: _atproto.<domain> TXT "did=did:web:ptharbor.net" + A record to wisp
+  IP; full resolution chain documented.
+- Key rotation procedure (did:web has NO recovery — test rotation while
+  stakes zero); key custody table (owner = business, primary = owner's
+  password manager, backup = sealed physical, never git/stdout/logs).
+
+### Key artifact: .hermes/plans/2026-08-08_030000-ptharbor-atproto-migration.md
+12-task Phase 1 (scaffold → consolidated 6-8 page IA site build → wisp.place
+deploy → DNS for handle → generate did:web identity → deploy did doc →
+provision Protobase PDS (gated) → create account → Bluesky presence → DNS
+cutover w/ rollback → archive/validate → write blueprint) + Phase 2 (Marque
+transfer, SSG rebuild, custom lexicons com.ptharbor.billboard.{location,
+availability,campaign}, community handles, full migration tool). Contains:
+- Decision Log table (19 decisions with rationale) — a reusable governance
+  pattern for migration projects.
+- Doer/Reviewer red-team pattern: co-located red_team_* files, finding IDs
+  PLAN-nn/CODE-nn/SEC-nn/RED-nn/UX-nn, RESOLVED annotations, immutable by
+  convention, different model for reviewer.
+- wispctl deploy WITHOUT --spa for multi-page brochure sites (real 404s to
+  surface broken links — deliberate contrast with sifter's --spa); WISPCTL_DB
+  env default, never hardcode machine paths.
+- DNS cutover runbook: record old A/AAAA, lower TTL 300s ≥24h, pre-verify
+  `curl --resolve`, rollback procedure.
+- Keygen script spec (scripts/generate-did-keys.mjs): Secp256k1Keypair.create()
+  → jwk() → public x/y to did-web/ptharbor.net/.well-known/jwk-values.json,
+  private hex to ~/.config/ptharbor/ 0o600.
+- Verification checklist with negative checks (no lorem ipsum, no
+  editmysite/weebly/mojopages refs, no http:// links, key not in git history).
+- Content migration: wget mirror BEFORE any DNS change; SHA-256 manifest gate.
+
+### Key artifact: references/existing-site/ (the raw material)
+- Full wget mirror www.ptharbor.com/: 36 HTML pages + 34 image assets +
+  theme CSS/JS + Cloudflare email-decode script (references/
+  existing-site/www.ptharbor.com/...). BACKUP_MANIFEST.txt lists sizes.
+- SITE_INVENTORY.md: 16-page Weebly inventory (locations with GPS, advertisers,
+  blog archive 2011-2013, contact david.singletary@gmail.com routed via
+  sales@ptharbor.com).
+- red_team_review_and_remediation.md: SEC-01…07 (cleartext HTTP, Weebly form
+  endpoint, jQuery 1.8.3 CVE-laden, http iframes, exposed Gmail w/ cfemail,
+  dead mojopages widget), RED-01…07 (duplication, bad GPS data, 5 placeholder
+  blog posts, stale news, lapsed clients as current), UX-01…11 (no viewport,
+  zero h1, missing alt, 16-item nav, 11-13px text, broken form, rotted links,
+  lorem ipsum page, testamonials typo) → converted to requirements R1–R9 for
+  the replacement site. Template for auditing any legacy site pre-migration.
+
+### Deployment methods (planned)
+- `wispctl deploy --path . --site ptharbor --yes --db "$WISPCTL_DB"
+  psingletary.com` (no --spa); custom domain mapping via wisp.place dashboard;
+  minimal did.json site `--site ptharbor-net` for ptharbor.net.
+- Handle verification: `curl public.api.bsky.app/xrpc/com.atproto.identity.
+  resolveHandle?handle=ptharbor.com`.
+
+### Conventions
+- AGENTS.md is PRIMARY agent instruction file (.hermes.md secondary — inverse
+  emphasis vs sifter): load impeccable skill for any UI work; plan pointer;
+  red-team README pointer BEFORE any work (binding).
+- .gitignore: identical shared key blocklist (below) + node_modules, build/,
+  dist/, .zed/ ignored (contrast: sifter commits .zed/).
+- Secret paths referenced: ~/.config/ptharbor/did-web-private-key.hex,
+  ~/.config/wispctl/state.sqlite. Files that MAY hold secrets (flag only,
+  contents not read): none in-repo; key lives outside repo by design.
+
+---
+
+## Cross-repo shared patterns
+
+1. Tangled git remotes for everything (git@tangled.org:did:plc:* or
+   psingletary.com/*) + wisp.place for static hosting via wispctl; custom
+   domain mapping via dashboard.
+2. AGENTS.md Quick Reference table (repo/create/deploy/live URL) in both;
+   .hermes.md for Hermes-specific instructions (skill list, credential
+   locations, conventions).
+3. .gitignore key blocklist identical in both (the pattern set from the
+   ptharbor red-team PLAN-06 fix): *.pem, *.key, *-key.txt, private-key*,
+   keys*, *keypair*, *.jwk, *.hex + !package-lock.json + .env* + ~* OneDrive.
+4. did:web private key convention: ~/.config/<app>/did-web-private-key.hex,
+   mode 0o600, never in git — sifter .hermes.md and ptharbor plan agree.
+5. Credential management → Bitwarden ("Porkbun API" item; per-project folders).
+6. Red-team review culture: sifter loads adversarial-red-team-review skill;
+   ptharbor has a standing reviewer with binding red_team_* files. Findings
+   flow into plans as acceptance gates.
+7. XRPC always through @atproto/api Agent / BrowserOAuthClient — no raw
+   fetch anywhere; scopes via 'atproto transition:generic'.
+8. Theme reuse: web_themes Tangled repo + sync-theme.sh build-time pull
+   (proven in sifter, available to all projects).
+9. Author-in-the-loop verification: agents code, author runs destructive
+   live tests (sifter M2/M4 HARD STOPS; ptharbor owner sign-offs).
+10. Pure-logic engines with dependency-injected API functions (sifter
+    src/lib/*) are the framework's unit-testable core; UI shells stay thin.
+11. Vendor-directory reuse (vendor/ in sifter, lifted from Verifier):
+    copy auth+layout kit, change domain constants, redeploy client metadata.
+
+---
+
+## Framework candidates (ranked, top 10)
+
+1. scan.js runScan — DI-injected paged scan + fail-closed trustworthy flag.
+   Pure, tested, generic across PDSes; base for any account-analysis tool.
+2. extract.js extractBlobRefs — the only generic blob-ref walker handling all
+   shapes incl. hydrated CIDs; needed by every record-processing tool.
+3. Auth kit (AuthContext + Login + LoginCallback + ProtectedRoute +
+   client-metadata.json) — the vendor/ pattern proven twice; scaffold any
+   ATProto SPA by copying and changing APP_BASE.
+4. cleanup.js — reference-and-delete blob deletion mechanism with listBlobs
+   verification, validate:false retry, temp NSID + sweep; the known way to
+   delete blobs at all.
+5. rateLimit.js RateLimitTracker — header-driven write-budget pacing;
+   reusable for any write-heavy client (posts, records, cleanup).
+6. backup.js — getBlob normalization + jszip manifest bundle + download
+   helper; drop-in data-export utility.
+7. sync-theme.sh + ThemeContext.js — build-time theme pipeline (Tangled
+   web_themes pull) + dark-mode provider; cross-project theming.
+8. did:web identity kit (ptharbor did-web-serving.md + plan Task 5/6) —
+   keygen script, did.json template, DNS records, rotation/custody, serving
+   options; the did:web playbook.
+9. Small-biz migration runbook (ptharbor plan) — decision log + red-team
+   pattern + DNS cutover w/ rollback + verification checklist + site audit
+   template (red_team_review_and_remediation.md R1–R9).
+10. Deploy conventions — wispctl wrapper (WISPCTL_DB env, --spa decision
+    rule), Tangled main/deploy two-branch flow, .zed tasks; standardize
+    every repo's deploy path.
diff --git a/docs/plans/framework-review/slicer.md b/docs/plans/framework-review/slicer.md
new file mode 100644
index 0000000..59baad1
--- /dev/null
+++ b/docs/plans/framework-review/slicer.md
@@ -0,0 +1,362 @@
+# Slicer + Timer — Component & Method Review (for modular ATProto framework)
+
+Reviewed 2026-09-06 (read-only) by Hermes subagent.
+Repos: /Users/patricksingletary/dev/slicer and /Users/patricksingletary/dev/timer.
+Both are CRA (react-scripts 5.0.1) JavaScript SPAs, OAuth-based, deployed to
+wisp.place, git remote = Tangled (source backup only). No secrets found in
+repo files; potential secret-holding files flagged inline.
+
+---
+
+## slicer
+
+### Identity / purpose
+- Slicer = "Slice wide panoramas into 5-10 vertical segments and publish them as a
+  single Bluesky gallery post." Live: https://slicer.psingletary.com.
+  Evidence: package.json description, README.md:1-8.
+- Fully client-side image pipeline (upload -> crop -> slice -> encode -> preview ->
+  publish -> verify). README.md:19-51.
+- Repo remote: git@tangled.org:did:plc:xg2rdgmaw5cxd6c55mno5ysr; web
+  https://tangled.org/psingletary.com/slicer. AGENTS.md quick-ref.
+
+### Stack (package.json, all pinned)
+- @atproto/api 0.13.35 (CJS, pinned; "sifter set"), @atproto/lexicon 0.4.14,
+  @atproto/oauth-client-browser 0.3.30, zod 3.24.3 (overrides), react/react-dom
+  ^18.2.0, react-router-dom ^6.28.1, react-scripts 5.0.1. devDeps: @napi-rs/canvas
+  ^1.0.7 (node canvas for tests), testing-library. package.json:6-57.
+- Scripts: start / build / test / eject (all react-scripts). package.json:18-23.
+- Pin rationale: 0.20.x line is ESM-only, breaks CRA webpack; gallery types ship
+  only in 0.20.9+, so 0.13.35 has no gallery type => hand-built embed + raw XRPC.
+  docs/RESEARCH.md "PIN DECISION LOCKED".
+- jest infra hacks (needed for any framework consumer): moduleNameMapper maps
+  multiformats subpaths to CJS builds; transformIgnorePatterns allows
+  @atproto|unicode-segmenter|multiformats; setupTests.js polyfills
+  TextEncoder/TextDecoder. package.json:30-39, src/setupTests.js:1-8.
+
+### Deploy / build / auth methods
+- Build+deploy: `npm run build` then
+  `wispctl deploy --path ./build --site slicer --spa --yes --db ~/.config/wispctl/state.sqlite psingletary.com`
+  AGENTS.md, README.md:72-78, TODO.md:278. --spa documented in wispctl 1.1.3
+  (installed /opt/homebrew/bin/wispctl, npm latest 1.2.0). docs/RESEARCH.md.
+- Tangled push = source backup ONLY, never deploys (Tangled Sites NOT configured).
+  AGENTS.md, README.md:77-78.
+- OAuth: BrowserOAuthClient (oauth-client-browser 0.3.30) with client metadata
+  FETCHED from /client-metadata.json at startup (single source of truth, no drift);
+  handleResolver https://public.api.bsky.app; plcDirectoryUrl https://plc.directory;
+  init() auto-restores session (IndexedDB persistence inside the lib). AuthContext.js:22-56.
+- OAuth redirect: BrowserRouter + /login/callback (verifier-proven pattern; NOT site
+  root). docs/RESEARCH.md "M1 DEVIATION".
+- Scope: `atproto transition:generic` (verifier's exact string). client-metadata.json:8.
+- Metadata: client_id = https://slicer.psingletary.com/client-metadata.json,
+  redirect_uris [/login/callback], grant_types [authorization_code, refresh_token],
+  dpop_bound_access_tokens true, token_endpoint_auth_method none. client-metadata.json:1-19.
+- Secret handling: no app passwords; OAuth only (TODO.md:323). .gitignore blocks
+  *.pem/*.key/*.hex/keys*/private-key*, .env, red-team-output/ (public-repo rule).
+  Porkbun API keys in Bitwarden ("Porkbun API" item) per .hermes.md.
+
+### Components (src/, file -> what it does -> interface)
+
+lib (pure, unit-tested):
+- src/lib/publish.js — gallery publish flow: sequential uploadBlob x N then
+  createRecord with hand-constructed app.bsky.embed.gallery embed; lexicon-validates
+  client-side BEFORE sending; RichText facet detection; optional selfLabels.
+  Exports: validateGalleryEmbed(embed), buildPostRecord({text, blobRefs, alts,
+  aspectRatio, labels, agent}) -> record, publishGallery({agent, did, blobs, alts,
+  aspectRatio, text, labels, onProgress, pacing}) -> {uri, cid, permalink};
+  const VALID_SELF_LABELS. NOTE: api 0.13.35 uploadBlob signature is
+  uploadBlob(blobBody, {headers}) — blob IS the body (publish.js:148-157).
+  Items need $type 'app.bsky.embed.gallery#image' discriminator (union).
+- src/lib/rateLimit.js — PDS rate-limit honoring: retryDelayFromError(err) parses
+  Retry-After (sec/HTTP-date) then RateLimit-Reset (epoch); isRetryable(err) (429,
+  5xx only); withBackoff(fn, {maxRetries=5, baseDelayMs=1000, maxDelayMs=30000,
+  onRetry}) exponential backoff w/ header override; sequentialWithPacing(items, fn,
+  {interRequestDelayMs=250}) sequential map, each item wrapped in backoff.
+  Constants DEFAULT_* exported. Reusable as-is.
+- src/lib/verify.js — post-publish hydration verification: analyzeGalleryEmbed(
+  thread, expectedItems) -> {hydrated, failure, embedType, itemCount, viewItems,
+  observedPresets}; presetFromUrl(url) parses /{preset}/plain/{did}/{cid}@fmt;
+  verifyPost({agent, uri, expectedItems, maxPollMs=10000, onAttempt}) polls
+  getPostThread w/ backoff (500ms base, 2x, max 2s); deletePost({agent, did, uri})
+  deletes by rkey (auto-delete on unhydrated embed — "no broken public posts").
+- src/lib/alt.js — alt-text composer: buildAlts(total, sharedDescription, overrides)
+  template "{n} of {total} — {description}" (clean when description empty);
+  allAltsValid(alts) publish gate (all non-empty). DEFAULT_ALT_TEMPLATE exported.
+- src/lib/encode.js — canvas slice encoding: encodeSlice({source, rect,
+  targetLongEdge=2000, maxBytes=2000000, canvasFactory, minQuality=0.6,
+  maxQuality=0.95, maxQualityIterations=6}) -> {blob,width,height,quality,over};
+  ONE drawImage per slice (seam guard); WebP quality binary search; encodeAllSlices
+  (global shared-long-edge reduction, max 3 x 10%, all slices identical dims);
+  decodeImage(blob, {imageOrientation:'from-image'}) EXIF-aware via
+  createImageBitmap, Image fallback; computeOutputSize never upscales;
+  defaultCanvasFactory (OffscreenCanvas -> document canvas -> throw). Tests use
+  @napi-rs/canvas (toBuffer path preferred over convertToBlob).
+- src/lib/geometry.js — pure slice geometry: computeSliceGrid({srcWidth, srcHeight,
+  cropRect, n}) -> {slices, sliceWidth, sliceHeight, effectiveCrop} (width trimmed
+  divisible by N symmetrically, integer px); suggestCrop({srcWidth, srcHeight, n,
+  targetSliceAspect}) largest centered crop, never upscales, warnings when a slice
+  axis > 4000; normalizeAspect accepts "w:h"/{w,h}/number; MIN_SLICES=5,
+  MAX_SLICES=10 (carousel threshold treated as volatile — lives here, not inline).
+- src/lib/cropViewport.js — pure pan/zoom viewport math: clampScale, fitScale,
+  clampOffset, initialViewport, zoomAt (cursor-fixed zoom), panBy, screenToSource,
+  clampCropRect (crop cannot leave source), getSliceGridLines, sourceRectToScreen.
+- src/lib/carousel.js — pure swipe/crop-nudge logic: clampIndex(index,n),
+  resolveIndex(index, dragDeltaX, threshold, n), nudgeCrop(crop, dx, dy, imgW,
+  imgH, step). Wired to pointer events by simulator.
+- src/lib/url.js — open-redirect guard: isSafeReturnUrl(raw, origin) (origin-relative
+  "/" paths minus "//host", or same-origin absolute https/http only, max 2048 chars);
+  safeReturnUrl(raw, origin, fallback='/'). Red-team SEC-01 pattern.
+
+contexts:
+- src/contexts/AuthContext.js — THE reusable OAuth provider: fetch /client-metadata.json,
+  new BrowserOAuthClient({clientMetadata, handleResolver, plcDirectoryUrl}), init()
+  auto-restore, build Agent from session (`new Agent(session)` — OAuth session is
+  Agent-compatible, "sifter pattern"), login(handle, returnUrl) via client.signIn
+  with JSON {returnUrl} state, logout() via session.signOut(). Provides {client,
+  session, agent, loading, error, isAuthenticated, login, logout} + useAuth() hook.
+
+components/pages:
+- src/App.jsx — BrowserRouter routes: /login, /login/callback, / (ProtectedRoute),
+  * -> Navigate "/".
+- src/pages/Home.js — full pipeline wiring: 50MB source cap, debounced (300ms)
+  encode, publish w/ progress, verify, auto-delete on unhydrated embed, permalink
+  result. Owns the publish state machine idle|publishing|verifying|done|deleted|error.
+- src/components/Login/Login.js — handle entry + safeReturnUrl redirect, auto-redirect
+  when already authed.
+- src/components/Login/LoginCallback.js — OAuth return landing: redirect to
+  safeReturnUrl or /login.
+- src/components/ProtectedRoute.jsx — gates children behind session; builds
+  /login?returnUrl=... (origin + pathname + search) when unauthenticated.
+- src/components/Crop/CropUI.jsx — canvas pan/zoom crop UI, presets 5x4:5, 6x4:5,
+  8x4:5, 5x1:1, aspect select, slice-grid overlay, red safe-zone box, arrow-key
+  nudge; pure logic delegated to cropViewport/geometry/carousel libs.
+- src/components/Carousel/CarouselSimulator.jsx — Bluesky swipe preview (pointer
+  events, 20% threshold, setPointerCapture guarded for jsdom), k/N badge, arrow
+  keys, "stitch check" edge-to-edge strip; object URLs revoked on unmount.
+- src/components/Alt/AltPanel.jsx — alt text composer UI (shared description 1000-char
+  cap, per-slice overrides) + self-label checkboxes (sexual/nudity/porn/graphic-media);
+  publish button gated on allAltsValid.
+
+data/schema:
+- src/lexicons/gallery.json — app.bsky.embed.gallery transcribed byte-for-byte from
+  upstream (sha256 6348fe...89083, TODO.md M0). Registered on the shared lexicons
+  instance via Lexicons.add() then validated with lexicons.validate(
+  'app.bsky.embed.gallery#main', embed) — validate() RETURNS {success,error}, does
+  not throw for nested failures; blob fields checked via instanceof BlobRef.
+  docs/RESEARCH.md "M8 schema discovery".
+- public/client-metadata.json — see Methods; pinned by test
+  src/__tests__/clientMetadata.test.js.
+
+### Conventions
+- AGENTS.md: project rules + Quick Reference table (repo, remote, wisp deploy cmd,
+  live site) + Deploy + AT Protocol sections. .hermes.md: Hermes-specific (skills to
+  load, conventions, credentials locations). TODO.md: milestone-by-milestone with
+  [x] acceptance evidence, red-team decision log (D1/D2/D3/D4), guardrails list,
+  open questions, out-of-scope. Both TODO.md's point to archived PLAN-*.md as
+  source of truth; do not re-open decided questions.
+- red-team-output/ present (2026-08-19-slicer-redteam.md plan review,
+  2026-08-19-slicer-code-redteam.md code review), gitignored (public-repo rule).
+- Testing: Jest via react-scripts; 129 tests at M8/M9 (geometry, encode, alt,
+  rateLimit, publish, verify, url, carousel, cropViewport, cropUI, carouselSimulator,
+  altPanel, clientMetadata suites). Fixtures F1-F5 documented TODO.md:250-254.
+- 14 guardrails TODO.md:285-303 (no hardcoded bsky.social PDS, one drawImage per
+  slice, integer pixels, identical aspectRatio, alt mandatory, never log tokens/
+  DPoP keys/session objects, never commit /tmp/wisp-oauth-session.json, no upscale).
+- .zed/tasks.json committed: Build, Test, Deploy to wisp.place, Push to Tangled,
+  Git status, Open Tangled repo.
+- .hermes/project.yaml generated by project-init.sh: type atproto-app, wisp site
+  slicer spa:true, tangled site_enabled:false.
+- No emojis in code/docs (no-emojis skill); CRA never Vite (family guardrail).
+- OAuth caveat: client-metadata.json is single source of truth; AuthContext fetches
+  it at startup; opaque failures if client_id/redirect/scope drift; Jest pins them.
+
+---
+
+## timer
+
+### Identity / purpose
+- timer = "Time-boxed moderation lists (T-7/T-30/T-90) and DM reminder bot."
+  Web app sorts blocks into lists; bot DMs when list items are due for removal.
+  Live: https://timer.psingletary.com. AGENTS.md, README.md:1-3.
+- Source of truth: PLAN-timer.md (archived ~/dev/_shared/docs/plans/archive/).
+  AGENTS.md; decision log §1 and guardrails §15 binding.
+- Repo remote (AUTHORITATIVE, AGENTS.md): git@tangled.org:did:plc:lauzdywpxgdmxeqd4ejy44zc
+  (note .hermes.md + .hermes/project.yaml say git@tangled.org:psingletary.com/timer —
+  STALE path-form remote; AGENTS.md notes the bare-DID form is correct; plan draft
+  typo'd ...ejj44zc).
+
+### Stack (package.json)
+- @atproto/api 0.20.41 (latest line), @atproto/oauth-client-browser 0.5.4, react
+  18.2.0, react-dom 18.2.0, react-router-dom ^6.28.1, react-scripts 5.0.1.
+  NO @atproto/lexicon, NO zod override, NO jest moduleNameMapper hacks. package.json:1-27.
+  S0 spike (TODO.md:22-32) proved webpack 5 bundles atproto 0.20.41/oauth 0.5.4 with
+  zero config — the ESM problem slicer avoided is solved here; framework should
+  target these pins.
+- Scripts: start/build/test/eject (react-scripts). package.json:14-19.
+- homepage: https://timer.psingletary.com.
+
+### Deploy / build / auth methods
+- Build+deploy: `npm run build` then
+  `wispctl deploy --path ./build --site timer --spa --yes --db ~/.config/wispctl/state.sqlite psingletary.com`
+  AGENTS.md, TODO.md:101. Tangled push never deploys (AGENTS.md explicitly corrects
+  README.md:23-33 template text and .hermes.md "auto-deploy via Sites" claim).
+- OAuth: same AuthContext pattern as slicer (fetch metadata, BrowserOAuthClient,
+  init() auto-restore + auto-callback — auto-callback verified in 0.5.4 typings,
+  TODO.md:60-62). HandleResolver public.api.bsky.app, plcDirectoryUrl plc.directory.
+- Scope: `atproto transition:chat.bsky` (chat scope needed for the DM bot path;
+  broader than slicer's transition:generic). client-metadata.json:9.
+- Metadata: redirect_uris [https://timer.psingletary.com/oauth/callback] — NOTE
+  mismatch with App.js routes which define /login/callback; BrowserOAuthClient
+  0.5.4 auto-completes the callback in init() so no React route needed (the
+  /login/callback LoginCallback component is likely vestigial slicer-template code;
+  flag for live-test at S11). contacts = burner@psingletary.com placeholder.
+- DID:WEB: .hermes.md mentions ~/.config/timer/did-web-private-key.hex (0o600) —
+  file not present in repo (expected, it lives in ~/.config); repo itself uses
+  did:plc (project.yaml did_web_domain: null).
+- Bot (bot/): Mac Studio 2022 local process, NOT part of web deploy. Auth =
+  Bluesky APP PASSWORD (env BLUESKY_HANDLE + BLUESKY_APP_PASSWORD via dotenv;
+  DM-scoped password, plan §4b), agent = new BskyAgent({service:
+  'https://bsky.social'}), agent.login(). scheduler.ts:7-30. bot/.env holds the
+  password, never git (TODO.md:89; .gitignore blocks .env + bot/*.db + bot/logs/).
+  NOTE: AGENTS.md/README claim bot/.env.example exists; on disk bot/ contains ONLY
+  scheduler.ts + schema.sql (no .env.example, no package.json) — flag.
+
+### Components
+Web app (src/):
+- src/contexts/AuthContext.js — byte-identical pattern to slicer's (fetch metadata
+  at startup, BrowserOAuthClient init, Agent from session, login w/ state,
+  logout). Only diff: comment notes chat scope comes from metadata. Reusable verbatim.
+- src/contexts/ToastContext.js — NEW vs slicer: minimal toast provider
+  {message, showToast}, 4s auto-dismiss, role=status. useToast() hook.
+- src/lib/url.js — exact copy of slicer's safeReturnUrl guard.
+- src/lib/lists.js — NEW (2026-09-06 21:00, actively developed): canonical four
+  lists as data: LIST_DEFS [{name 'T-7'/'T-30'/'T-90'/'♾️'(ETERNITY_NAME),
+  durationMs (7/30/90 days or null), purpose 'app.bsky.graph.defs#modlist'}];
+  durationForListName(name); ensureListsPlan(existingLists) -> {missing, duplicates}
+  (pure); ensureListsOnAccount(agent, did) -> {created:[{name,uri}], missing,
+  duplicates} — getLists then createRecord app.bsky.graph.list for each missing;
+  reports duplicates, never auto-deletes. Exact names are a contract (bot maps
+  NAME -> duration).
+- src/lib/lists.test.js — Jest for the pure part (LIST_DEFS exact-name contract,
+  duration map, ensureListsPlan missing/duplicates). src/__tests__/__fixtures__/
+  exists but EMPTY.
+- src/App.js — routes /login, /login/callback, /logout (new vs slicer), / gated by
+  ProtectedRoute; AuthProvider + ToastProvider.
+- src/components/Home.js — placeholder (S3 scope): shows did + scope, agent ready
+  note. Real block board comes S5+.
+- src/components/Login/Login.js, LoginCallback.js — same safeReturnUrl pattern.
+- src/components/Logout.js — NEW: route-level logout (calls logout() when authed,
+  else /login).
+- src/components/ProtectedRoute.js — identical to slicer's.
+- public/client-metadata.json — see Methods (has logo_uri/tos_uri/policy_uri/
+  contacts fields slicer lacks — richer template).
+
+Bot (bot/):
+- bot/scheduler.ts — THE reusable scheduled-bot method: BskyAgent + app password
+  login (NOT OAuth — bots run headless, DM-scoped password), better-sqlite3 (WAL,
+  foreign_keys ON), poll loop every 5 min (POLL_INTERVAL_MS, setInterval after
+  initial tick). Per active user: cacheUserListDurations(did) via public.api.bsky.app
+  getLists (paginated, cursor, limit 50); pollUser(did, convoId): getLists(agent
+  scope) -> listItemsFor(did, listUri) getList paginated limit 100 -> compute
+  dueAt = createdAt + durationMs -> if due and not already in reminders ->
+  agent.chat.bsky.convo.sendMessage (DM) -> INSERT OR IGNORE reminders row;
+  on 400/403 DM failure -> users.active=0 (opt-out/error handling, plan S10);
+  generic errors logged + continue (failures don't crash). msToDays helper.
+  NOTE: reads lists via the USER's session scope (agent.app.bsky.graph.getLists
+  actor:did) and public API for list items; write path = DMs only, never user repos
+  (guardrail 5, remind-only bot).
+- bot/schema.sql — users(did PK, handle, convo_id, active, last_polled_at,
+  created_at, updated_at), reminders(user_did, list_uri, listitem_uri, subject_did,
+  due_at, sent_at, PK(user_did,listitem_uri), FK cascade), idx_users_active,
+  idx_reminders_user, view v_due_reminders (active users with unsent reminders).
+  Deployment plan: launchd or pm2 always-on, logs -> bot/logs/ (TODO.md:107-109).
+
+### Conventions
+- Same AGENTS.md / .hermes.md / TODO.md / .hermes/project.yaml / .zed/tasks.json
+  family shape as slicer. Timer has NO red-team-output/ dir yet (no red-team run on
+  file yet).
+- S0-S13 milestone discipline in TODO.md with acceptance criteria in [brackets]
+  copied from plan; status log dated entries; gate S0 (§17 spike) mandatory.
+- Guardrails: no version changes without owner approval (guardrail 12), bot never
+  writes user repos (5), no firehose (poll-based sync), no emojis in code except the
+  ♾️ eternity list name (13), lists stay public.
+- Testing: Jest via react-scripts; fixtures in src/__tests__/__fixtures__/ (dir
+  exists, empty); lists.test.js green per TODO S13. React-scripts test requires the
+  multiformats/TextEncoder hacks? — NO: timer has no jest config hacks; S0 spike
+  implies 0.20.x tests work (TextEncoder polyfill NOT in setupTests — none exists
+  yet; watch this when adding the first component test).
+- .gitignore adds bot runtime artifacts (bot/logs/, bot/*.db*) beyond slicer's.
+
+---
+
+## Cross-repo shared patterns
+
+1. AuthContext.js is copy-paste identical across slicer and timer (fetch
+   /client-metadata.json at startup -> BrowserOAuthClient -> init() -> Agent(session)
+   -> login/logout with {returnUrl} state) — the single highest-value framework
+   candidate. Files: slicer src/contexts/AuthContext.js, timer src/contexts/AuthContext.js.
+2. client-metadata.json as fetched single source of truth + Jest pin test
+   (slicer has the test; timer relies on same mechanism). Guardrail 5.
+3. safeReturnUrl open-redirect guard duplicated verbatim (src/lib/url.js both).
+4. Login.js / LoginCallback.js / ProtectedRoute.js trios near-identical; timer adds
+   Logout.js route. BrowserRouter + /login/callback (slicer) vs /oauth/callback
+   metadata w/ auto-callback (timer, 0.5.4) — version-dependent callback handling.
+5. wispctl deploy command identical shape, differing only in --site name; Tangled
+   push = backup in both (timer AGENTS.md corrects its own README/.hermes.md).
+6. Pure-logic-in-src/lib + Jest separation (slicer fully; timer starting with
+   lists.js) — deterministic, unit-testable, no DOM.
+7. Record write pattern: agent.*.repo.createRecord w/ collection + repo:did (slicer
+   publish.js createRecord app.bsky.feed.post; timer lists.js createRecord
+   app.bsky.graph.list). deleteRecord by rkey (slicer verify.js deletePost).
+8. Pagination cursor loop pattern (timer bot getLists/getList; idiom also in
+   slicer's context for future list reads).
+9. Sequential-with-pacing + Retry-After/RateLimit-Reset honoring rate limiter
+   (slicer rateLimit.js) — reusable for any N-request XRPC fan-out.
+10. Version-line knowledge: CJS-pinned 0.13.35/0.3.30 + jest hacks (slicer) vs
+    ESM 0.20.41/0.5.4 zero-config (timer, proven by S0 spike) — framework should
+    standardize on the 0.20.x line.
+11. Self-label attach pattern (com.atproto.label.defs#selfLabels) and lexicon
+    pre-validation (Lexicons.add + validate) before send (slicer publish.js).
+12. Plan-sourced guardrails (never hardcode bsky.social for writes, resolve PDS
+    from session; alt mandatory; no secrets in build; no emojis) are enforced
+    identically in both.
+
+---
+
+## FRAMEWORK CANDIDATES (top reusable building blocks)
+
+1. AuthContext + client-metadata.json pattern (fetch-at-startup, BrowserOAuthClient,
+   Agent(session), signIn state, signOut) — proven in 2 repos, both version lines;
+   parameterize scope/handleResolver. Evidence: both AuthContext.js files, both
+   client-metadata.json.
+2. safeReturnUrl / isSafeReturnUrl open-redirect guard — verbatim duplicate;
+   trivial to extract to @shared/lib/url.
+3. rateLimit.js (withBackoff + retryDelayFromError + sequentialWithPacing) —
+   self-contained, tested (10 tests), no React dep; reuse for any XRPC fan-out.
+4. Login/LoginCallback/ProtectedRoute/Logout route quartet — near-duplicate across
+   repos; extract with configurable redirect URI + version-aware callback handling
+   (0.3.30 explicit route vs 0.5.4 auto-callback).
+5. ensureListsOnAccount + LIST_DEFS (timer lists.js) — canonical data-driven list
+   creation w/ duplicate reporting; generalizes to "ensure N named records exist".
+6. publish.js gallery pipeline (uploadBlob x N -> createRecord, BlobRef items w/
+   $type discriminator, selfLabels, lexicon pre-validation) — the flagship slicer
+   method; requires the gallery lexicon file + lexicon 0.4.x/0.7.x validator.
+7. verify.js (analyzeGalleryEmbed + verifyPost poll + deletePost auto-delete) —
+   "publish, verify hydration, auto-delete on failure" pattern reusable for any
+   embed type.
+8. buildAlts/allAltsValid alt-text composer + gating — small, tested, required by
+   accessibility posture; reusable for any multi-image tool.
+9. encode.js / geometry.js / cropViewport.js / carousel.js — image-pipeline libs
+   (single drawImage, never-upscale, integer px, identical dims, cursor-fixed
+   zoom); slicer-specific but the encode rules generalize to any image-upload tool.
+10. bot/scheduler.ts + schema.sql — headless app-password bot template (poll loop,
+    paginated reads, idempotent INSERT OR IGNORE, opt-out on DM failure); generalize
+    to any reminder/notifier bot. Plus: the S0-proven dependency set
+    (@atproto/api 0.20.41 + oauth-client-browser 0.5.4 under CRA/webpack, zero
+    config) as the framework's baseline pins.
+
+## Secret-hygiene flags (by filename only)
+- timer/bot/.env — holds BLUESKY_APP_PASSWORD (DM-scoped) + handle; gitignored,
+  NOT in repo (only referenced in scheduler.ts env reads).
+- ~/.config/timer/did-web-private-key.hex — referenced in timer .hermes.md; outside
+  repo (expected; repo has no did:web).
+- No keys/tokens found in any reviewed repo file.
diff --git a/docs/plans/framework-review/verifier.md b/docs/plans/framework-review/verifier.md
new file mode 100644
index 0000000..7fa391d
--- /dev/null
+++ b/docs/plans/framework-review/verifier.md
@@ -0,0 +1,351 @@
+# Framework Review Notes: verifier + altifier
+
+Reviewer: read-only subagent, 2026-09-06. Both repos reviewed in place at
+/Users/patricksingletary/dev/{verifier,altifier}. Nothing modified. No secrets
+found in source; all keys handled via env/localStorage and redacted here.
+
+Both repos are CRA (react-scripts 5.0.1) SPAs on Tangled remotes:
+- verifier origin: git@tangled.org:did:plc:hkla7ikm6duiuvtmtd7aa6tr (866 commits, main clean)
+- altifier origin: git@tangled.org:did:plc:h46uvw3x22m5utvqgfjb2ax5 (869 commits, main clean)
+Altifier is a FORK of verifier (its plan doc says "Transform the existing
+Verifier SPA into Altifier", altifier/.hermes/plans/2025-08-05_altifier-mvp.md:3).
+
+---
+
+## verifier
+
+### Purpose (first lines)
+- README.md:1-3 "Verifier — A lightweight tool for creating and managing Bluesky
+  verification records (`app.bsky.graph.verification`) on an account's PDS."
+- DESIGN.md:3 "Create and manage AT Protocol verification records — decentralized,
+  transparent, minimal." (frontmatter name/description; rest is impeccable
+  design-token YAML).
+- PRODUCT.md:1-2 "# Product <!-- impeccable:product-schema 1 -->" — positions it
+  as both a working tool and a reference implementation of the
+  app.bsky.graph.verification lexicon. Deployed at verifier.psingletary.com
+  (Wisp) and psingletary.tngl.io/verifier (Tangled sub-path) (PRODUCT.md:36).
+- AGENTS.md:1-3 — only instruction: load `impeccable` skill for UI work.
+
+### Stack (verifier/package.json + package-lock.json)
+- @atproto/api ^0.13.22 (lock resolves 0.13.35), @atproto/oauth-client-browser
+  ^0.3.15 (0.3.15), @atproto/oauth-client-node ^0.2.4 (0.2.11 — installed but
+  never imported; browser-only app), react/react-dom ^18.2.0,
+  react-router-dom ^6.28.1, react-scripts ^5.0.1, dev cross-env ^7.0.3.
+- No test framework deps; no CSS framework; single App.css + theme import.
+
+### Methods (from package.json scripts)
+- start: "npm run sync:theme && react-scripts start"
+- build: "npm run sync:theme && react-scripts build"
+- test: "react-scripts test --watchAll=false" (no test files exist; dead script)
+- sync:theme: "bash scripts/sync-theme.sh"
+- Deployment (README.md:45): `wispctl deploy <handle> --path ./build --site
+  verifier --spa` for Wisp.place; Tangled via repo Sites deploy-dir `/build`;
+  any static host w/ SPA fallback. vercel.json exists but no Vercel deploy is
+  documented in README (vercel.json rewrites "/api/(.*)" -> https://api.cred.blue/api/$1
+  and all else -> /index.html; headers add CORS to /client-metadata.json and
+  /api/*). No PUBLIC_URL mention anywhere in repo (deployment context only).
+
+### Auth / session (core reusable method)
+- src/contexts/AuthContext.js (105 lines, the whole OAuth story):
+  - On mount fetches `/client-metadata.json` (single source of truth, "P6"),
+    constructs `new BrowserOAuthClient({ clientMetadata, handleResolver:
+    'https://public.api.bsky.app', plcDirectoryUrl: 'https://plc.directory' })`,
+    calls oauthClient.init(), stores initResult.session (AuthContext.js:22-41).
+  - login(handle, returnUrl): signIn with JSON-stringified {returnUrl} state
+    (AuthContext.js:55-67). logout(): session.signOut() then hard redirect '/'.
+  - Exposes {client, session, loading, error, isAuthenticated, login, logout}
+    via context + useAuth() hook that throws outside provider.
+  - NO hand-written PKCE/DPoP code — entirely @atproto/oauth-client-browser.
+    DPoP is on via client metadata `dpop_bound_access_tokens: true`
+    (public/client-metadata.json:19).
+- public/client-metadata.json: client_id https://verifier.psingletary.com/
+  client-metadata.json; redirect_uris verifier.psingletary.com/login/callback AND
+  psingletary.tngl.io/verifier/login/callback (dual-host OAuth); scope
+  "atproto transition:generic"; token_endpoint_auth_method none; application_type web.
+- src/components/Login/Login.js: handle input -> login(); on authenticated,
+  window.location.replace(returnUrl) (default 'https://verifier.psingletary.com/
+  verifier', absolute, Login.js:11,16). Uses localStorage key auth_redirect_url.
+- src/components/Login/LoginCallback.js: after init, reads returnUrl from query
+  and window.location.replace() (absolute URLs work; LoginCallback.js:13-16).
+- src/components/ProtectedRoute.jsx: builds absolute returnUrl
+  `${window.location.origin}${pathname}${search}`, hard-redirects to
+  /login?returnUrl=... if unauthenticated (ProtectedRoute.jsx:12-14). Full-page
+  redirects (not <Navigate>) — sub-path/session-safe choice.
+- src/contexts/ThemeContext.js: localStorage 'theme' key; toggles body.dark-mode;
+  default dark. Used in index.js wrapping App.
+
+### XRPC / record code (all in src/components/Verifier/Verifier.js, 583 lines)
+- Session -> agent: `new Agent(session)` from @atproto/api (Verifier.js:72).
+  All repo writes use agent.api.com.atproto.repo.*:
+  - createRecord single (Verifier.js:169-173)
+  - listRecords cursor-paginated, limit 100 (Verifier.js:80-83)
+  - deleteRecord revoke (Verifier.js:307-309)
+  - putRecord re-issue on same rkey with swap semantics absent (plain putRecord,
+    Verifier.js:384) — NOTE: no swapRecord guard here (altifier's applier has one)
+  - applyWrites bulk create, chunked 200/BULK_WRITE_CHUNK, counting per-item
+    create.uri results (Verifier.js:252-281, 445-467) — P1
+  - App-view reads: app.bsky.actor.getProfile (188), getProfiles chunked 25 for
+    staleness check (336), graph.getLists / getList for curatelists (117, 230).
+- Reusable helper functions defined inline (module scope, not exported):
+  - paginate(fn, params, onPage) — generic cursor loop that auto-detects the
+    array list-key from the response (Verifier.js:15-30). THE canonical
+    pagination util across both repos' live code (altifier copies its own
+    variants per-file).
+  - rkeyFromUri(uri) = uri.split('/').pop() (Verifier.js:33).
+- Verification record shape (P2 dedupe index Map<subjectDid,{uri,rkey,handle,
+  displayName,createdAt}> in a ref): { $type:'app.bsky.graph.verification',
+  subject, handle, displayName, createdAt } (Verifier.js:168, 243-246).
+- Typeahead: raw fetch (no SDK) to
+  https://public.api.bsky.app/xrpc/app.bsky.actor.searchActorsTypeahead?q=&limit=10,
+  300ms debounce (Verifier.js:138-161).
+- Share intent: https://bsky.app/intent/compose?text=... link after verify
+  (Verifier.js:201-207).
+- P7 import/export: JSON export via Blob+createObjectURL download
+  (Verifier.js:401-417); import re-validates against dedupe index then bulk
+  applyWrites chunks (Verifier.js:420-482).
+- P4 staleness: getProfiles in chunks of 25 vs stored index; marks stale (handle/
+  displayName changed) or gone (profile no longer resolves / batch error);
+  re-issue via putRecord (Verifier.js:324-398).
+- UI components: VerifierForm.jsx (mode select account|list, handle input or
+  list select, P5 trust caveat copy); VerifierSuggestions.jsx (typeahead
+  dropdown w/ avatar, onSelect(handle)); Verifier.js owns statusMessage/type
+  pattern and per-item action buttons (revoke, re-issue, stale/gone badges).
+
+### Crypto / secrets
+- generateSecret.js:5 lines, node crypto.randomBytes(64).toString('hex')
+  printing "Your new SECRET_KEY is: ..." — orphaned boilerplate; NOT referenced
+  anywhere in src/scripts/docs of either repo. No .env used; no real secret
+  values in repo. supabase.js reads REACT_APP_SUPABASE_URL/_ANON_KEY but is
+  dead code with an UNINSTALLED dep (@supabase/supabase-js not in package.json
+  or lockfile). No Bitwarden/Keychain references in-repo; scripts/sync-theme.sh
+  comment notes "Requires SSH access to Tangled at build time (Apple Keychain
+  on this Mac)" (scripts/sync-theme.sh:17).
+
+### Dead code in verifier (tracked, never imported — verified by import scan)
+- src/utils/api.js (fetchWithTimeout 10s AbortController, fetchWithRetry w/
+  linear backoff, no-retry on 401/403 — good patterns but unused),
+- src/utils/didUtils.js (resolveDIDToHandle via plc.directory alsoKnownAs,
+  isDID for did:plc:/did:web:),
+- src/accountData.js (1343 lines! legacy account-scoring fetchScores to
+  api.cred.blue/api/score, buildAccountData*, buildAnalysisNarrative — leftover
+  from an entirely different earlier app),
+- src/config/allowlist.js (ALLOWED_ACCOUNTS = Dame's did:plc + 'dame.is' +
+  isAccountAllowed() console-logging gate — legacy single-user gate),
+- src/lib/supabase.js (above).
+
+### Scripts / agent dir / conventions
+- scripts/sync-theme.sh (41 lines): build-time shallow clone/fetch of
+  git@tangled.org:psingletary.com/web_themes into ~/.cache/web_themes, hard
+  reset to origin/main, copies themes/<name>/theme.css+index.css to
+  src/styles/theme (default theme witchsky-cyan; env overrides WEB_THEMES_REPO,
+  THEME_DEST). src/styles/theme/* is gitignored ("synced from web_themes,
+  build-time pull, do not commit", .gitignore). Prebuild step wires it.
+- agent/: PATCH-webux.md (a reusable "PROMPT" doc for porting UX fixes —
+  oEmbed embeds + login flow — to another codebase), plan_css_reset.md,
+  plan_themes.md (unimplemented theme picker plan, referenced PRODUCT.md).
+- Conventions: patch-led development labeled P1..P7 in code comments (P1 bulk
+  applyWrites, P2 load-once dedupe index, P3 paginate helper, P4 staleness+
+  putRecord reissue, P5 trust caveat, P6 client-metadata fetch, P7 JSON
+  import/export). impeccable skill for UI; PRODUCT/DESIGN in impeccable
+  schemas. No TODO.md, no red-team-output/, no tests, no CI config beyond
+  .github/FUNDING.yml. 42 tracked files. index.html CRA template w/ og tags
+  pointing at verifier.psingletary.com. Design: verifier DESIGN.md is YAML
+  tokens only; colors named verification-teal etc.; App.css only 79 lines of
+  app-specific additions (base in theme css) — .gitignore comments out /build
+  so verifier's build dir is NOT ignored (odd; altifier's is ignored).
+
+---
+
+## altifier
+
+### Purpose (first lines)
+- README.md:1-3 "Altifier — Scan your Bluesky posts for missing alt text and fix
+  them with AI-generated descriptions."
+- DESIGN.md:3 same description (impeccable YAML + long narrative rules: 18px
+  floor, flat-by-default, ghost status colors).
+- PRODUCT.md: Purpose = scan PDS for posts w/ missing image/video alt, generate
+  Section-508 alt text via AI, review/edit, apply; deployed altifier.psingletary.com
+  (wisp.place) and tangled.org/psingletary.com/altifier (PRODUCT.md tail).
+  Note PRODUCT.md:33 & capabilities still describe delete-and-recreate, which
+  the CODE no longer does (see drift section).
+- AGENTS.md adds: "AGENTS.md is the primary agent instructions file; .hermes.md
+  (if present) is secondary" + impeccable pointer.
+
+### Stack — IDENTICAL to verifier (same package.json versions, same resolved
+lockfile versions 0.13.35/0.3.15/0.2.11/5.0.1). Extra tracked baggage:
+- .agents/skills/impeccable/ — full vendored impeccable skill bundle
+  (~120 files) + skills-lock.json pinning pbakaus/impeccable w/ computedHash
+  (altifier/skills-lock.json). verifier has neither.
+- .hermes/plans/2025-08-05_altifier-mvp.md — original fork plan.
+
+### Methods (package.json scripts; diff vs verifier: test adds --passWithNoTests)
+- start/build same sync:theme prestep. No AI/build-time env anymore: README
+  AI Setup section (README.md:43-51) says export REACT_APP_GEMINI_API_KEY at
+  build; the CODE replaced this with BYO-key in localStorage (drift, see below).
+- Deploy: wispctl deploy ... --site altifier --spa (README.md:37), Tangled
+  Sites /build. .gitignore ignores /build (verifier does not).
+
+### Feature modules (altifier-only code — the extraction goldmine)
+- src/utils/postScanner.js (148): scanImagePosts(agent, did, {startCursor,
+  onPage}) — enumerates app.bsky.feed.post via com.atproto.repo.listRecords
+  limit 100 cursor loop (resumable; onPage({cursor,hits}) for progress
+  persistence). parseEmbed() normalizes THREE embed shapes to alt-able media
+  entries: app.bsky.embed.images (per-image alt), app.bsky.embed.recordWithMedia
+  (media.images alt), app.bsky.embed.video (single embed.alt). Exports
+  blobCdnUrl(did, cid) = https://cdn.bsky.app/img/feed_fullsize/plain/{did}/{cid}@jpeg
+  (postScanner.js:18-20,146). Records keep originalValue (exact object P1
+  writes back), rkey from uri, isReply, missingAltCount.
+- src/utils/altApplier.js (105): applyAltText(agent, did, post, approvedAlts) —
+  IN-PLACE edit: getRecord -> JSON-clone -> mutate ONLY alt fields per embed
+  shape (applyAltEdits) -> putRecord with swapRecord: cid guard; on
+  InvalidSwap/409 retries once after re-fetch, else throws. Returns putRecord
+  data {uri,cid} (altApplier.js:58-105). Preserves URI/engagement.
+- src/utils/altGenerator.js (135): generateAltText(imageUrl, postText) — fetch
+  image from CDN -> blob -> base64 -> POST to Google Gemini
+  generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent
+  (line 13; NOTE model 1.5-flash, docs claim 2.5 Flash) with Section-508
+  prompt; batchGenerateAltText(images, postText) per-image with error-inline.
+  BYO key: getGeminiKey()/isGeminiConfigured() read localStorage
+  'altifier.geminiKey'; NEVER bundled at build.
+- src/components/Altifier/Altifier.js (315): orchestration — scan w/ resume
+  (saved cursor per-DID in localStorage 'altifier.scan.{did}'), Gemini key
+  settings panel, filter show-missing-only, status box pattern (same as
+  verifier's statusMessage/statusType). P4 BYO key, P6 saved scan.
+- src/components/Altifier/BlueskyPostEmbed.js (109): React component
+  BlueskyPostEmbed({did, rkey, className}) — oEmbed from
+  https://embed.bsky.app/oembed?url=https://bsky.app/profile/{did}/post/{rkey},
+  injects returned html via dangerouslySetInnerHTML, then loads
+  embed.bsky.app/static/embed.js once and calls window.bluesky.scan(el) to
+  hydrate blockquote -> live iframe; graceful fallback link + loading state.
+  This exact pattern is also documented as a transferable prompt in
+  altifier/agent/PROMPT-ui-changes.md and verifier/agent/PATCH-webux.md.
+- src/components/Altifier/AltifierPostCard.js (164): per-post review card:
+  approve/reject per image, old->new diff modal (P7) with confirm, apply
+  button, error box. AltifierImageCard.js (105): image thumbnail from cdnUrl,
+  lazy-loaded; textarea maxLength 1000 + char count; Generate (dynamic import
+  of altGenerator) / Approve / Skip; video placeholder when no cdnUrl.
+
+### Dead/legacy code in altifier (tracked, never imported)
+- src/components/Verifier/{Verifier.js(301-lines — OLD pre-P1-P7 verifier),
+  VerifierForm.jsx, VerifierSuggestions.jsx} — unreferenced leftovers;
+  PRODUCT.md "Undecided" item acknowledges them.
+- Identical dead set to verifier: src/utils/api.js, src/utils/didUtils.js,
+  src/accountData.js (1343, same file), src/config/allowlist.js, src/lib/supabase.js.
+
+### Conventions
+- agent/: PATCH-altifier.md is a rigorous multi-patch spec (P1 in-place
+  putRecord CRITICAL, P2 scan-PDS-not-AppView HIGH, P3 widen embed coverage
+  HIGH, P4 BYO Gemini key HIGH...) — evidence the P-tag patch workflow is a
+  house convention. agent/PROMPT-ui-changes.md reusable porting prompt.
+- Design tokens in DESIGN.md + .impeccable/design.json + witchsky-cyan theme
+  via sync-theme.sh; accessibility rules codified in DESIGN.md prose.
+- "No emojis in code, docs, comments, or generated text" (PRODUCT.md tail).
+- Build from /tmp to dodge OneDrive Files On-Demand ETIMEDOUT (PRODUCT.md:54).
+- App.css 472 lines here vs 79 in verifier (never slimmed).
+- 199 tracked files (impeccable bundle dominates).
+
+---
+
+## Duplication-Drift
+
+Nearly-identical lineage confirmed: 42 shared tracked file-paths; ~20 byte-for-byte
+identical, rest cosmetic renames + feature drift. Altifier fork predates verifier's
+P1-P7 hardening; verifier's newer Verifier feature work never flowed back to
+altifier's frozen legacy copy and vice versa.
+
+### Byte-identical files (verified diff SAME)
+vercel.json, generateSecret.js, scripts/sync-theme.sh, src/index.js,
+src/accountData.js (1343 lines), src/config/allowlist.js, src/contexts/
+ThemeContext.js, src/lib/supabase.js, src/utils/api.js, src/utils/didUtils.js,
+src/components/Verifier/VerifierSuggestions.jsx, src/styles/theme/{index,theme}.css
+(untracked build-pull, same source), src/styles/variables.css,
+agent/plan_css_reset.md, agent/plan_themes.md, .github/FUNDING.yml, vercel.json.
+Implication: dead code is dead in BOTH; theme plumbing is shared; the
+sync-theme.sh + web_themes pattern is already a functioning shared component.
+
+### Near-identical with only brand/URL substitution
+- DESIGN.md: same token structure, color names renamed (verification-teal ->
+  protocol-teal, slate-* -> *-blue-gray, ink -> deep-navy...) — SAME hex values
+  re-keyed; altifier adds narrative design rules & ghost-status/18px rules.
+- README/PRODUCT/index.html/client-metadata.json: swapped app name/domain;
+  redirect_uris pair pattern identical (custom domain + psingletary.tngl.io/<app>
+  sub-path).
+- AuthContext.js: functionally identical; only the fetch comment/label differs
+  ("P6" comment in verifier vs fuller comment in altifier), behavior same.
+- AGENTS.md: altifier adds "AGENTS.md primary, .hermes.md secondary" line.
+- package.json: test script differs (verifier lacks --passWithNoTests); nothing
+  else. package-lock resolved versions identical.
+- Login.js/LoginCallback.js/ProtectedRoute.jsx: same flow; drift in return-URL
+  strategy: verifier uses ABSOLUTE default 'https://verifier.psingletary.com/
+  verifier' + window.location.replace everywhere (works across hosts/sub-path);
+  altifier uses RELATIVE '/altifier' + navigate() in LoginCallback, and
+  ProtectedRoute drops the origin from returnUrl. Verifier's is the
+  dual-host/sub-path-safe variant; altifier's is simpler but assumes same-host.
+- Navbar/Footer: brand text only.
+- App.css: same header comment pattern; verifier 79 lines vs altifier 472
+  (verifier stripped duplicate base when adopting theme CSS, altifier kept
+  full app stylesheet incl. older layout styles).
+- .gitignore: verifier comments OUT /build (build dir untracked-but-present),
+  altifier ignores /build; altifier additionally ignores a wisp placeholder.
+- Verifier.js copy: 583 lines (verifier) vs 301 lines (altifier legacy copy):
+  verifier gained P1 applyWrites bulk-200 w/ per-item results counting, P2
+  load-once Map dedupe index (altifier copy re-derives from scratch each call),
+  P3 shared paginate() helper (altifier copy hand-rolls cursor loops inline in
+  fetchAllVerifications/fetchUserLists), P4 staleness check + putRecord
+  re-issue + gone detection, P7 JSON import/export. Altifier copy has none of
+  these. VerifierForm.jsx: verifier adds P5 trust-caveat + duplicate-date note.
+- AuthContext comment/behavior drift minor (see above). LoginCallback verifier
+  keeps an explanatory comment about absolute returnUrls altifier lacks.
+
+### Behavioral drift between DOCS and CODE (both repos)
+- altifier README.md:16-17,23-24 + PRODUCT.md + .hermes plan Q1 say posts are
+  DELETE-and-RECREATED (engagement lost, putRecord rejected by app view per
+  atproto discussion #3038). Current altifier code (altApplier.js, Altifier.js
+  UI copy, agent/PATCH-altifier.md P1) does IN-PLACE putRecord + swapRecord
+  preserving URI — README/PRODUCT/plan are stale on strategy.
+- altifier README/PRODUCT/hermes-plan say Gemini 2.5 Flash via build-time
+  REACT_APP_GEMINI_API_KEY; code uses gemini-1.5-flash model with BYO
+  localStorage key (altGenerator.js:11-13). Two generations of drift.
+- verifier PRODUCT.md says "~259 kB JS ... no icon library" etc; App.css after
+  theming is 79 lines so "single CSS file" constraint mostly holds.
+
+### Framework extraction insight (what is genuinely duplicated vs single-use)
+- GENUINELY duplicated across both live codebases (worth framework-izing):
+  OAuth bootstrap (AuthContext + client-metadata + Login/LoginCallback/
+  ProtectedRoute), theme build-pull (sync-theme.sh + witchsky-cyan), paginated
+  cursor-loop (verifier paginate() vs altifier per-file loops),
+  statusMessage/statusType UX pattern, dead util modules (api.js retry/timeout
+  helpers, didUtils) that are GOOD generic utils currently stranded,
+  oEmbed post embed (BlueskyPostEmbed + porting prompts).
+- Single-use per product (framework as plugins/templates): verification record
+  CRUD (Verifier.js), alt-text scan/apply/generate (postScanner/altApplier/
+  altGenerator), Gemini BYO-key panel.
+
+## FRAMEWORK CANDIDATES (ranked; see summary reply)
+1. OAuth SPA bootstrap (AuthContext pattern + client-metadata.json + dual-host
+   redirect_uris + Login/Callback/ProtectedRoute) — identical in both, correct
+   per atproto OAuth spec, ~200 lines shared.
+2. Generic atproto cursor-paginator (paginate(fn, params, onPage)) — verifier
+   has the clean version; altifier re-implements per call.
+3. Post/media embed normalization (parseEmbed in postScanner.js) — handles
+   images/recordWithMedia/video uniformly; reusable by any post-review tool.
+4. In-place record editor w/ swapRecord guard (applyAltText pattern, generic
+   getRecord-mutate-putRecord-swap-retry) — beats delete-recreate; reusable for
+   ANY lexicon edit.
+5. Bluesky oEmbed post embed React component (BlueskyPostEmbed) — already
+   packaged as a porting prompt in agent/PROMPT-ui-changes.md.
+6. Resumable long-scan pattern (cursor + hits persisted to localStorage,
+   resume/restart UI) — needed by any full-history tool.
+7. sync-theme.sh + web_themes(witchsky-cyan) build-time theme pull — already
+   shared; formalize as scaffolding step.
+8. fetchWithTimeout/fetchWithRetry (utils/api.js) — solid, currently dead;
+   promote into shared lib for raw-XRPC/aux endpoints.
+9. didUtils (plc.directory resolution + did:web support) — generic identity
+   helpers, currently dead.
+10. BYO-key AI integration pattern (localStorage key + direct provider call,
+    no server) — altifier P4; reusable for any AI feature (Gemini/Ollama).
+
+No secrets or credentials present in either repo (generateSecret.js is inert;
+supabase/Gemini keys are env/localStorage only). Secret-adjacent files to be
+aware of: src/lib/supabase.js (expects REACT_APP_SUPABASE_* env), none hold
+values.
diff --git a/docs/plans/framework-review/zodiac.md b/docs/plans/framework-review/zodiac.md
new file mode 100644
index 0000000..71ee347
--- /dev/null
+++ b/docs/plans/framework-review/zodiac.md
@@ -0,0 +1,336 @@
+# zodiac + acct-tools — ATProto Framework Component/Method Extraction
+
+Read-only review by framework-extraction subagent. Reviewed 2026-09-06 (EDT).
+No files modified. No secrets reproduced — PII/credentials referenced by file
+path only, per source repos' own AGENTS.md rules.
+
+Repo paths:
+- zodiac:        /Users/patricksingletary/dev/zodiac
+- acct-tools:    /Users/patricksingletary/dev/acct-tools
+
+Git remotes (both Tangled):
+- zodiac origin:     git@tangled.org:did:plc:mo67zhweppd37oncmu3p5yji  (DID-style repo path, verified via git remote -v)
+- acct-tools origin: git@tangled.org:psingletary.com/acct-tools  (acct-tools/AGENTS.md:9)
+Note: Tangled accepts BOTH remote path styles (DID plc vs account/name).
+
+---
+
+## zodiac
+
+### KEY FINDING UP FRONT
+zodiac is NOT an ATProto app. package.json (/Users/patricksingletary/dev/zodiac/package.json)
+has zero atproto dependencies; no OAuth, no record ops, no PDS calls, no
+session persistence anywhere in src/. It is a private single-page astrology
+compatibility site (Next.js App Router + static export) whose only links to
+the ATProto world are (a) hosting on Tangled Sites, (b) deployment via the
+out/ static-export contract, and (c) shared repo conventions (AGENTS.md,
+impeccable design workflow, red-team-output practice). Framework value is
+therefore: reference Next.js static-export + Tangled deployment template,
+client-only "data in the URL" sharing pattern, env-split public/private
+config discipline, and repo hygiene conventions — NOT atproto methods.
+
+### Purpose / product
+README.md:1-37 — private astrology compatibility: visitor enters birthday,
+gets Western sign + Chinese zodiac + compatibility vs a FIXED admin profile
+(Virgo + Fire Dragon). No accounts, no tracking, no storage; computed
+client-side. Share token encoded in URL (base64url + embedded expiry, 48h).
+PRODUCT.md:19-56 confirms: no analytics, no cookies w/ PII, English only, no
+i18n planned, admin birthday only in env vars.
+
+### Stack (package.json)
+- next 16.3.0 (pinned), react 19.2.8, react-dom 19.2.8
+- devDeps: tailwindcss ^4 + @tailwindcss/postcss, typescript ^5, vitest ^4.1.10,
+  @vitejs/plugin-react ^6.0.5, eslint ^9 + eslint-config-next 16.3.0
+- Scripts (package.json:5-12): dev=next dev, build=next build, start=next start,
+  lint=eslint, test=vitest run, test:watch=vitest
+- tsconfig: strict, ES2017, bundler resolution, "@/*" -> "./src/*"
+  (tsconfig.json paths)
+- vitest.config.ts: globals:true, environment:"node", alias @ -> src
+- eslint.config.mjs: eslint-config-next core-web-vitals + typescript; ignores
+  .next/ out/ build/ next-env.d.ts
+
+### Framework pattern: next.config.ts (fully static)
+next.config.ts:5 output:"export"; poweredByHeader:false; security headers are
+host/CDN layer concern (comment). Layout.tsx additionally emits CSP via
+<meta httpEquiv> because static export has no server runtime
+(src/app/layout.tsx:36-39). DEPLOY.md:17-45: Tangled auto-detects output export
+and deploys out/; NEVER deploy .next/ (RSC payloads/sourcemaps). robots.txt
+disallows /r (share path) — public/robots.txt.
+
+### Deployment methods (DEPLOY.md fully read)
+- Option A Tangled (recommended): push repo; Tangled Sites deploys out/.
+  CNAME zodiac -> tangled.org (DEPLOY.md:15-25).
+- Option B wisp.place: `wispctl --spa --dir out zodiac.psingletary.com`
+  (DEPLOY.md:30) — note acct-tools uses `wispctl deploy --path ./build ...`.
+- Option C Vercel / D any static host.
+- Security headers table (DEPLOY.md:47-64): CSP/meta baseline on wisp; `_headers`
+  file on Cloudflare/Netlify; vercel.json on Vercel; Tangled needs support ticket.
+- Env is BUILD-TIME ONLY (baked into static output) (DEPLOY.md:66-78). Admin
+  phone is NOT in the client bundle: sms: link uses EMPTY recipient.
+- Post-deploy verification curl: `grep -oE '\+1[0-9]{10}'` on served HTML must
+  return nothing (DEPLOY.md:89).
+- Env vars (.env.example): ADMIN_PHONE (required, E.164; value redacted in
+  repo by placeholder +1XXXXXXXXXX), ADMIN_NICKNAME (default "me"),
+  SHARE_TOKEN_TTL_SECONDS (default 172800).
+
+### src/ inventory (all files read except CSS files skimmed)
+app/ (App Router, 3 routes):
+- src/app/layout.tsx — root layout; Geist fonts via next/font/google; CSP meta;
+  StarryBackground mounted globally.
+- src/app/page.tsx — landing page (server component); calls
+  getClientAdminConfig() + getAdminConfig() at build; renders BirthdayForm.
+- src/app/r/page.tsx — "use client"; ?t= token decode path; useSearchParams +
+  Suspense (Next 16 requirement); decodeReport pure during render via useMemo;
+  renders full report w/ "unverified/self-attested" notice + expiry states.
+  RATING_COLORS map for badges (r/page.tsx:8-13). robots disallowed.
+- src/app/{globals,tokens,stars}.css — tokens.css = design-system custom props
+  (:root oklch scale, --z-* 40+ tokens); stars.css = parallax keyframes.
+
+components/ (all client):
+- BirthdayForm.tsx — M/D/Y selects + optional name; UTC-anchored validation
+  (real-date check via Date.UTC roundtrip); on submit runs computeVisitorProfile
+  + buildCompatibilityReport; swaps to CompatibilityReport view (unmounts form).
+- CompatibilityReport.tsx — full report UI; client-side share-token generation
+  (encodeReport + buildShareUrl, no server round trip); identityBorderStyle()
+  top-edge split gradient (western color left, element color right) via
+  westernColorVar/elementColorVar; renders SmsLink after token exists.
+- SmsLink.tsx — empty-recipient sms: URI builder: separator "?" for Android /
+  "&" for iOS (buildSmsLink, SmsLink.tsx:79-81); useSyncExternalStore for
+  UA-based isMobile; clipboard copy fallback for desktop; copied state 2s.
+- ZodiacSigns.tsx — ZodiacSignIcon SVG constellation paths per sign + star
+  points; exports CHINESE_ANIMAL_SYMBOL unicode map + twinkleCSS string.
+- StarryBackground.tsx — pure CSS 3-layer parallax stars (box-shadow
+  technique), zero JS animation.
+
+lib/:
+- astrology/western.ts — getWesternSign(date): WesternSign — pure UTC month/day
+  range table, Capricorn year-boundary special case. Types: ZodiacSign (12),
+  Element, Modality, Planet, WesternSign interface.
+- astrology/chinese.ts — getChineseZodiac(date): ChineseZodiac via baked
+  LUNAR_NEW_YEAR table 1900-2100 (keyed record of [y,m,d]); stem-branch
+  index = (year-4) % 10 / % 12; isSixHarming(a,b) pair check. Types:
+  ChineseAnimal, ChineseElement, YinYang, HeavenlyStem, ChineseZodiac.
+- astrology/index.ts — barrel re-export of both + types.
+- compatibility/data.ts — ALL static tables + domain types: Rating,
+  WesternCompatibility, ChineseCompatibility (w/ elementInteraction +
+  isSixHarming), VisitorProfile, CompatibilityReport (computedAt ISO string);
+  WESTERN_COMPATIBILITY (12 signs vs Virgo), CHINESE_COMPATIBILITY
+  (animal x element), ANIMAL_PROFILES (elementModifiers per animal).
+- compatibility/engine.ts — computeVisitorProfile(birthDate, name?) ->
+  VisitorProfile; buildCompatibilityReport(visitor) -> CompatibilityReport;
+  computeOverall averages Western+Chinese numeric rating (Excellent=4..1) into
+  overall; generateDos/generateDonts produce context-aware advice strings.
+  Re-exports data.ts types/tables.
+- config/admin.ts — TWO-config split pattern (reusable):
+  getAdminConfig(): AdminConfig reads process.env (ADMIN_PHONE, ADMIN_NICKNAME,
+  SHARE_TOKEN_TTL_SECONDS) — server/build only; getClientAdminConfig():
+  ClientAdminConfig strips phone + nickname so the client bundle leaks no PII.
+- share/tokens.ts — client-side stateless "data-in-URL" pattern (reusable):
+  encodeReport(report, ttlSeconds=172800) -> base64url JSON {r, exp};
+  decodeReport(token) -> report|null (malformed/expired -> null);
+  buildShareUrl(token) -> `${origin}/r?t=...` w/ SSR guard.
+- zodiac-colors.ts — sign/stem -> CSS custom property maps (westernColorVar,
+  elementColorVar w/ fallback token).
+
+### Tests (vitest, 3 files, ~62 tests per README)
+- src/lib/share/__tests__/tokens.test.ts (106 ln) — roundtrip, expiry,
+  tamper/malformed -> null, URL safety. Uses full fixture CompatibilityReport.
+- src/lib/astrology/__tests__/astrology.test.ts (174 ln) — boundary dates,
+  LNY edges 1900-2100, six-harming pairs.
+- src/lib/compatibility/__tests__/engine.test.ts (137 ln) — report shape.
+Style: vitest globals + describe/it/expect, @ alias imports, inline fixtures.
+
+### Conventions (AGENTS.md fully read, 48 ln)
+- AGENTS.md is primary agent file; .hermes.md secondary.
+- impeccable skill must be loaded for ANY frontend/design work.
+- SECURITY RULES (zodiac/AGENTS.md:1-48, hardened after real past leak):
+  1. Never quote secrets/PII — reference type+location only.
+  2. red-team-output/ + audit artifacts gitignored, local-only; dispositions as
+     one-line commit messages; git add -A FORBIDDEN (stage by name); pre-commit
+     git status --short check.
+  3. No auto-executing tool state in git (.claude/, .cursor/, .impeccable/).
+  4. History rewrites need explicit owner approval; note post-force-push
+     exposure on tangled.org.
+  5. Deployable = out/ only; grep scan `\+1[0-9]{10}|ADMIN_` over out/.
+  6. OneDrive ETIMEDOUT workaround: stage to /tmp, work there.
+  7. wispctl OAuth residue: clear oauth_state rows in
+     ~/.config/wispctl/state.sqlite after failed flows.
+- .gitignore confirms: /out, /.next, .env*, red-team-output/, tool-state dirs.
+- no-emojis in code/docs (PRODUCT.md:87). WCAG AA, 48px touch targets.
+
+### red-team-output/ (local-only, gitignored; listing + v3 skim only)
+- final-report.md (mode 700), final-report-v3.md (newest, 2026-08-09).
+- v3 headings: Exec Summary, Findings Table, v2 disposition verification,
+  new findings F-101 (Critical: birthday re-leaked by committing an earlier
+  report), F-103 (Medium: stale wispctl OAuth state), F-104 (Medium: untracked
+  agent tooling w/ executable hooks), F-105 (High process: red-team-output
+  committed to git), F-108 (Low: CSP meta w/ unsafe-inline); attack chains,
+  PASS list, Top 3 risks, Redactions section.
+- Action items (v3 tail): history rewrite + remote GC for F-101/F-105 (treat
+  date as burned); F-003 forgeable self-attested share tokens = accepted risk
+  (was publicly documented in the committed ledger — remediation lesson:
+  a leak ledger must itself pass secret scan); F-104 one-line .gitignore fix.
+- Lesson for framework: security reports belong OUT of git; audit output dir
+  convention red-team-output/ + AGENTS.md rule set is a reusable template.
+- .impeccable/design.json + DESIGN.md + DESIGN-PROPOSAL.md document the
+  impeccable skill workflow (design-token YAML frontmatter, oklch scales,
+  colorblind analysis section).
+
+### Zodiac reusable assets for framework (ranked)
+1. out/-export Tangled/wisp deployment contract + DEPLOY.md template
+   (next.config.ts output:"export"; deploy out/ not .next/; host-level headers).
+2. share/tokens.ts stateless self-attested token-in-URL pattern (base64url,
+   embedded expiry, SSR-safe buildShareUrl) — useful for any no-backend share.
+3. config/admin.ts server/client config split (getXConfig vs getClientXConfig)
+   — env PII containment pattern.
+4. SmsLink.tsx empty-recipient sms: URI + UA separator + clipboard fallback.
+5. pure-UTC date handling convention in astrology modules (calendar dates not
+   moments) — generalizable to any birthday/date feature.
+6. Vitest + @ alias setup (vitest.config.ts) + inline-fixture test style.
+7. AGENTS.md security rule set + gitignore pattern (audit-dir, tool-state).
+8. impeccable design workflow (DESIGN.md tokens.css oklch pipeline).
+
+---
+
+## acct-tools
+
+### Status: SPEC-ONLY (no code)
+git ls-files (acct-tools, main @ 9104976): AGENTS.md, README.md, TODO.md,
+.hermes.md, .hermes/project.yaml, .gitignore, .zed/settings.json, .zed/tasks.json.
+NO package.json, NO src/, NO docs/plans/archive/PLAN-acct-tools.md (referenced
+as source of truth in TODO.md:7 but not committed in this repo — the manifest
+lives elsewhere, likely in another repo's docs/plans/). README.md structure
+block (README.md:35-49) shows intended tree only. So: everything below is
+EXTRACTED INTENT from README/AGENTS/TODO, not observed code.
+
+### Product intent ("Deck")
+Static AT Protocol account-management web app: manage one's own account —
+identity/PLC, follows hygiene, repo/blob audits, list tooling, alt-text,
+verification records, and high-risk PLC/DID:web ops. Live at
+acct-tools.psingletary.com. Handle psingletary.com (AGENTS.md:33).
+.project.yaml: type atproto-app; deploy wisp (site acct-tools, spa:true) +
+tangled site_enabled:1.
+
+### Intended stack (TODO.md:22-32, M0) — ALL framework-relevant decisions
+- Vite vanilla-ts, hash routing (#/page), browser-only, NO framework, NO SPA
+  fallback needed (hash routing), build target es2022, base './'.
+- SDK: @bsky/sdk + @atproto/lex (EXPLICITLY NOT @atproto/api — TODO.md:114).
+- OAuth: @atproto/oauth-client-browser.
+- client-zip (browser zip for blob backups), @noble/curves (dual-curve keys).
+- public/client-metadata.json: client_id/redirect = <DEPLOY_ORIGIN>;
+  scope "atproto transition:generic"; dpop true.
+- Hard bundle budget: total JS transfer <= 250 KB gzipped (TODO.md:16).
+- No tests/CI/linters; ONLY gate = `npm run build` clean under strict TS.
+- Deploy methods (AGENTS.md:14-29): push to Tangled (auto-deploy via Sites,
+  deploy dir configured in Tangled settings/sites) OR
+  `wispctl deploy --path ./build --site acct-tools --spa --yes --db
+  ~/.config/wispctl/state.sqlite psingletary.com`. NOTE: wisp path is ./build
+  (Vite outDir convention) vs zodiac's out/.
+- .hermes.md conventions: skills to load (atproto-development,
+  small-business-atproto-migration, plan, adversarial-red-team-review); plans
+  at .hermes/plans/YYYY-MM-DD_HHMMSS-slug.md; wispctl OAuth state sqlite path;
+  secrets in Bitwarden (Porkbun folder ref).
+- .hermes.md:22 references a local DID:WEB private key path
+  ~/.config/acct-tools/... (hex, 0o600) — reference only, no content read;
+  matches .gitignore key rules (never commit *.hex, keys*, etc.). .zed/
+  intentionally committed (tasks: build/test/deploy-wisp/push-tangled).
+
+### Intended components/methods (extract from TODO.md M1-M5, per module)
+lib/oauth.ts — BrowserOAuthClient setup; init/restore session (persistence
+across reload), signIn/signOut (handle entry redirects to PDS).
+lib/client.ts — wrap authed session in @atproto/lex Client (api.app.service);
+public-client fallback when signed out.
+lib/xrpc.ts — (a) cursor-loop paginator (listRecords etc.), (b) chunk() util,
+(c) applyWrites batcher at 200 writes/chunk with progress, (d) getProfiles x25
+helper (batch profile lookup; feeds viewer.following dedupe).
+lib/keys.ts — dual-curve keypair generation: secp256k1 (multicodec 0xe7 0x01)
+and p256 (0x80 0x24); base58btc + base64url encodings; did:key + Multikey
+construction; service-auth JWT signing (ES256K / ES256, low-S).
+lib/ui.ts — imperative DOM helpers: el(), table builder, toast, confirmDialog,
+progressBar, downloadBlob, typed-confirmation (hard gates), diff renderer,
+wizard-step component.
+lib/router.ts — hash router mapping #/x to page render fns.
+Pages (features F1-F7): home (session card + nav), identity (F1: resolve
+handle/DID, PDS endpoint, PLC audit log, change-handle form), follows (F2:
+follow-scan + category flags + selected/select-all unfollow via applyWrites
+w/ progress), repo (F3), lists (F4), media (F5), verify (F6), danger (F7).
+
+### Intended atproto operations per page (methods = framework gold)
+- F2 follows (TODO.md:50-53): listRecords cursor loop over follows; statuses
+  via getProfiles x25; unfollow selected via applyWrites (200/chunk, progress).
+- F3 repo/blob lifecycle (TODO.md:56-61): download repo .car; blob audit =
+  listBlobs vs CIDs referenced by describeRepo + listRecords; backup = blob
+  zip + manifest.json via client-zip; orphan delete pattern = write throwaway
+  record (place.wisp.deck.gc) referencing the blob then delete it, RE-CHECK
+  listBlobs, serial execution, typed "delete" gate; record browser
+  (describeRepo dropdown -> listRecords table -> JSON view -> delete confirm).
+- F4 lists (TODO.md:62-64): own lists + starter packs; copy list; list -> mod
+  list; combine lists; starter pack -> list; list from follows; follow all
+  members with dedupe via getProfiles viewer.following.
+- F5 media (TODO.md:65-67): scan own posts for images with empty alt
+  (incl. recordWithMedia embeds); alt fix via putRecord SAME rkey
+  (notes likes/replies preserved).
+- F6 verify (TODO.md:69-72): single verify = resolve handle -> DID +
+  displayName -> write app.bsky.graph.verification; bulk from own lists via
+  applyWrites with already-verified skip; manage table with Revoke;
+  duplicate detection BEFORE writing.
+- F7 danger zone (TODO.md:74-86) — PLC ops (did:plc only): identity state +
+  audit log; MANDATORY backup download before submit; add-recovery-key wizard
+  (key placed at rotationKeys index 0); advanced editor; shared submit flow:
+  requestPlcOperationSignature -> signPlcOperation -> DID-doc DIFF + 72h
+  window warning -> typed "apply" -> submitPlcOperation. HARD BLOCKS:
+  rotationKeys empty or >5, no overlap with current set; SOFT WARN on removing
+  PDS-recommended key. DID:WEB wizard (signed-out OK): mode A = files +
+  instructions only (ZERO network writes) / mode B = full setup incl.
+  createAccount with service-auth JWT; steps: inputs -> curve radio + FORCED
+  key download (no recovery-window warning in did:web) -> did.json build +
+  download -> verify hosting (CORS fallback w/ checkbox) -> INSTRUCTIONS.md
+  (A) or createAccount (B).
+- Boot (M5): main.ts — oauth init, router start, nav render. README 20 lines
+  max incl. one-paragraph Danger Zone warning.
+
+### Conventions / build gate (TODO.md:10-19, 94-117)
+- plan-intake style: source-of-truth PLAN doc "design is FINAL — do not
+  re-analyze or redesign"; implement exactly the manifest; one pass per file,
+  no refactor passes; ambiguity rule: pick simplest consistent option, note in
+  one line, keep moving (never stop to ask).
+- Acceptance checklist (TODO.md:94-109): dist/ static-only; signed-out pages =
+  identity inspector + did:web wizard; OAuth session survives reload; orphan
+  deletion re-verifies listBlobs; duplicate detection before verify writes;
+  did:key:z strings differ per curve and file records curve; mode A zero
+  writes; mode B JWT alg matches curve; no console errors; <= 250 KB gzip.
+- Out of scope (TODO.md:111-116): no @atproto/api patterns, no server code,
+  no env secrets, no framework, no redesign.
+- Security conventions: private keys gitignored by pattern (*.hex, keys*,
+  keypair*, *.pem...); .hermes.md points secrets to Bitwarden.
+
+### acct-tools framework candidates (spec'd, unbuilt — highest leverage)
+OAuth session mgmt, lex client wrapper w/ public fallback, xrpc cursor
+paginator + chunk + applyWrites 200-batcher + getProfiles x25, dual-curve
+keygen did:key/Multikey + service-auth JWT (ES256K/ES256 low-S), PLC op submit
+flow (requestPlcOperationSignature -> signPlcOperation -> diff -> submit),
+blob orphan audit/delete (listBlobs vs referenced CIDs; write-ref-then-delete
+gc trick), list/starter-pack transforms, alt-text scan + putRecord same-rkey,
+verification-record mgmt, hash-router SPA shell, client-metadata.json OAuth
+static-host pattern. NOTE: none of this is built yet — treat as a SPEC for
+framework module interfaces; the verifier (F6) feature is self-contained here
+(TODO.md:69-72) and is itself a reusable module pattern.
+
+---
+
+## Cross-repo observations
+- Two Tangled hosting contracts coexist: static Next out/ (zodiac) and Vite
+  dist/build + hash routing SPA (acct-tools spec). Framework scaffolds should
+  offer both.
+- Common conventions to codify: AGENTS.md quick-reference table (repo/remote/
+  wisp command/live URL), deploy-via-push-to-Tangled + optional wispctl manual
+  path, red-team-output/ local-only practice, no-emojis, secrets-in-Bitwarden,
+  .hermes/plans/ naming, wispctl oauth_state sqlite residue note.
+- None of the repos so far reference @atproto/api by choice: zodiac uses none;
+  acct-tools spec mandates @bsky/sdk + @atproto/lex. Framework should treat
+  @atproto/api as legacy and standardize on lex-first + oauth-client-browser.
+- Redaction notes: no secrets appear in this file. Files that hold/cite PII or
+  key material (flagged, never quoted): zodiac/.env.example (phone pattern),
+  zodiac red-team-output/*.md (local-only; v3 self-redacts), zodiac AGENTS.md
+  rule text, acct-tools/.hermes.md (DID:WEB key path), acct-tools/.gitignore
+  (key patterns), zodiac/AGENTS.md + zodiac/DEPLOY.md mention ADMIN_PHONE.
-- 
2.51.2