diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 432ea62..7291a6f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "Claude Code skills.", - "version": "1.0.0" + "version": "1.0.1" }, "plugins": [ { diff --git a/wherefore/log/2026-06-24-adr-positioning.md b/wherefore/log/2026-06-24-adr-positioning.md index fae9608..08fbcc1 100644 --- a/wherefore/log/2026-06-24-adr-positioning.md +++ b/wherefore/log/2026-06-24-adr-positioning.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Position against ADRs in one line, not a section +title: "Position against ADRs in one line, not a section" areas: [branding] topics: [positioning, docs] stories: [] @@ -21,7 +21,8 @@ keep the ADR keyword for discoverability only. automatically instead of dying in a wiki. - Acknowledge ADRs in one sentence, not a dedicated "Why not ADRs?" section. - Put "adr" and "architecture-decision-records" in the GitHub topics for search - traffic. Never put ADR in the product name. + traffic. +- Never put ADR in the product name. ## Why A whole ADR section reads defensive and anchors the product to the exact thing it diff --git a/wherefore/log/2026-06-24-dashboard-build-tool.md b/wherefore/log/2026-06-24-dashboard-build-tool.md index ecb1ea2..f4c22b9 100644 --- a/wherefore/log/2026-06-24-dashboard-build-tool.md +++ b/wherefore/log/2026-06-24-dashboard-build-tool.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Ship the dashboard as a build tool, not a fork +title: "Ship the dashboard as a build tool, not a fork" areas: [dashboard] topics: [distribution, build] stories: [] diff --git a/wherefore/log/2026-06-24-dashboard-schema-and-ui.md b/wherefore/log/2026-06-24-dashboard-schema-and-ui.md index 4bf0fa9..ef0dc8a 100644 --- a/wherefore/log/2026-06-24-dashboard-schema-and-ui.md +++ b/wherefore/log/2026-06-24-dashboard-schema-and-ui.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Dashboard reads source files and renders all states +title: "Dashboard reads source files and renders all states" areas: [dashboard] topics: [data-model, ui] stories: [] @@ -22,7 +22,7 @@ correcting an earlier draft schema that predated supersession and would not buil - The dashboard reads the per-entry and per-question source files directly and ignores INDEX.md and QUESTIONS.md, so index drift cannot corrupt the view. - Obsolete is handled on every surface: home, log list, detail banner, tag counts. - One "Show retired" toggle covers superseded and obsolete. +- One "Show retired" toggle covers superseded and obsolete. - Questions render their full body in an expandable card. - Tags show the full vocabulary with zero-count tags dimmed, counts active-only. - Dangling pointers (placeholder superseded-by, blank resolution_slug) never produce diff --git a/wherefore/log/2026-06-24-decision-supersession-model.md b/wherefore/log/2026-06-24-decision-supersession-model.md index 8f55936..33c1f43 100644 --- a/wherefore/log/2026-06-24-decision-supersession-model.md +++ b/wherefore/log/2026-06-24-decision-supersession-model.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Decision supersession model and status states +title: "Decision supersession model and status states" areas: [plugin] topics: [supersession, data-model] stories: [] diff --git a/wherefore/log/2026-06-24-package-in-repo.md b/wherefore/log/2026-06-24-package-in-repo.md index 29f31bd..cf92211 100644 --- a/wherefore/log/2026-06-24-package-in-repo.md +++ b/wherefore/log/2026-06-24-package-in-repo.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Dashboard package at packages/wherefore-dashboard in the wherefore repo +title: "Dashboard package at packages/wherefore-dashboard in the wherefore repo" areas: [repo-structure] topics: [publishing, ci] stories: [] diff --git a/wherefore/log/2026-06-24-package-separate-repo.md b/wherefore/log/2026-06-24-package-separate-repo.md index ad6be1a..284e665 100644 --- a/wherefore/log/2026-06-24-package-separate-repo.md +++ b/wherefore/log/2026-06-24-package-separate-repo.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Dashboard package in its own repo +title: "Dashboard package in its own repo" areas: [repo-structure] topics: [publishing] stories: [] diff --git a/wherefore/log/2026-06-24-rename-to-lore.md b/wherefore/log/2026-06-24-rename-to-lore.md index 9ec70fb..e9d4829 100644 --- a/wherefore/log/2026-06-24-rename-to-lore.md +++ b/wherefore/log/2026-06-24-rename-to-lore.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Rebrand to lore with plain-verb skill names +title: "Rebrand to lore with plain-verb skill names" areas: [branding] topics: [naming] stories: [] diff --git a/wherefore/log/2026-06-24-supersede-separate-skill.md b/wherefore/log/2026-06-24-supersede-separate-skill.md index 6f8590e..d146a25 100644 --- a/wherefore/log/2026-06-24-supersede-separate-skill.md +++ b/wherefore/log/2026-06-24-supersede-separate-skill.md @@ -1,6 +1,6 @@ --- date: 2026-06-24 -title: Manual supersession lives in its own skill +title: "Manual supersession lives in its own skill" areas: [plugin] topics: [supersession, skill-structure] stories: [] diff --git a/wherefore/log/2026-06-25-agents-md-cross-tool.md b/wherefore/log/2026-06-25-agents-md-cross-tool.md index 8ee658b..60a17a7 100644 --- a/wherefore/log/2026-06-25-agents-md-cross-tool.md +++ b/wherefore/log/2026-06-25-agents-md-cross-tool.md @@ -16,12 +16,12 @@ Wherefore's skills encode file conventions and workflows that aren't Claude-spec ## Decisions / outcomes - AGENTS.md at the repo root contains the wherefore data format plus capture, supersede, and question workflows as an actionable spec. - Claude Code imports it via @AGENTS.md in CLAUDE.md; Copilot gets a short .github/copilot-instructions.md pointing at it; Cursor and Codex read it natively. -- Tool-specific files are thin pointers, not copies -- one source of truth to prevent drift. +- Tool-specific files are thin pointers, not copies. One source of truth prevents drift. - AGENTS.md is kept lean (actionable spec, no rationale prose) because instruction-adherence drops as these files grow. - Sophisticated skill behaviors (multi-thread splitting, auto-supersession detection, question-resolution matching) are deliberately omitted: weaker models won't execute them reliably. ## Why -AGENTS.md is the emerging cross-agent standard (Linux Foundation, 30-plus tools), making it the right lowest-common-denominator surface. Copy-pasting the same rules across CLAUDE.md, copilot-instructions.md, and AGENTS.md is the main anti-pattern that causes divergence over time. The design principle: the log degrades gracefully -- any model can produce valid records by following AGENTS.md; Claude does the smarter orchestration on top. +AGENTS.md is the emerging cross-agent standard (Linux Foundation, 30-plus tools), making it the right lowest-common-denominator surface. Copy-pasting the same rules across CLAUDE.md, copilot-instructions.md, and AGENTS.md is the main anti-pattern that causes divergence over time. The design principle: the log degrades gracefully. Any model can produce valid records by following AGENTS.md; Claude does the smarter orchestration on top. ## Alternatives considered - MCP server wrapping operations as callable tools: the most robust cross-tool path since MCP is universally supported, but adds infrastructure that cuts against the plain-files, no-dependency wedge. Deferred; see Q-006. diff --git a/wherefore/log/2026-06-25-no-file-url-serving.md b/wherefore/log/2026-06-25-no-file-url-serving.md index 4328d91..76a3757 100644 --- a/wherefore/log/2026-06-25-no-file-url-serving.md +++ b/wherefore/log/2026-06-25-no-file-url-serving.md @@ -11,7 +11,7 @@ superseded_date: --- ## Summary -Astro emits absolute asset paths (`/_astro/...`), which resolve to the filesystem root under `file://` and break styles when a user double-clicks `dist/index.html`. We decided not to support file:// viewing -- the build output is HTTP-only. User confusion is addressed with documentation and a build-time hint rather than changing the asset path strategy. +Astro emits absolute asset paths (`/_astro/...`), which resolve to the filesystem root under `file://` and break styles when a user double-clicks `dist/index.html`. We decided not to support file:// viewing. The build output is HTTP-only. User confusion is addressed with documentation and a build-time hint rather than changing the asset path strategy. ## Decisions / outcomes - Keep Astro's default absolute asset paths; do not switch to relative paths for file:// compatibility. @@ -19,7 +19,7 @@ Astro emits absolute asset paths (`/_astro/...`), which resolve to the filesyste - Build command output will include a one-line hint directing users to serve rather than open the file. ## Why -Relative asset paths complicate sub-page routing and create their own class of bugs. The build output is always deployed over HTTP (Cloudflare Pages, etc.) where absolute paths are correct -- file:// is a local-preview edge case, not a deployment target. Documentation and a build hint fix the real problem (user confusion) at far lower cost than restructuring the asset strategy. +Relative asset paths complicate sub-page routing and create their own class of bugs. The build output is always deployed over HTTP (Cloudflare Pages, etc.) where absolute paths are correct; file:// is a local-preview edge case, not a deployment target. Documentation and a build hint fix the real problem (user confusion) at far lower cost than restructuring the asset strategy. ## Alternatives considered - Relative asset paths everywhere: rejected because they complicate sub-page routing and the root cause is that the build was never meant to be double-clicked. diff --git a/wherefore/log/2026-06-25-npm-asset-scope.md b/wherefore/log/2026-06-25-npm-asset-scope.md index 4aa0ed3..41d6a48 100644 --- a/wherefore/log/2026-06-25-npm-asset-scope.md +++ b/wherefore/log/2026-06-25-npm-asset-scope.md @@ -19,11 +19,11 @@ npm pack --dry-run is the verification ground truth. ## Decisions / outcomes - public/ ships: favicon.svg, PNG favicons (16, 32, 180), both lockup SVGs (dark/light), og-card.png. -- Brand source files live in brand/ and .github/assets -- not shipped to npm. +- Brand source files live in brand/ and .github/assets, not shipped to npm. - "files" whitelist: [bin, src, public, astro.config.mjs]. -- Docs (HOSTING.md etc.) stay in the repo but out of the tarball. README ships; its - images and links use absolute raw.githubusercontent URLs (npm does not resolve - repo-relative paths). +- Docs (HOSTING.md etc.) stay in the repo but out of the tarball. +- README ships; its images and links use absolute raw.githubusercontent URLs (npm + does not resolve repo-relative paths). ## Why A build tool's tarball should contain only what the tool needs to run. Brand source files @@ -37,6 +37,6 @@ applies to the README because npmjs.com serves it independently of the repo. ## Open questions / follow-ups - Q-005: Should the built site support file:// viewing via relative asset paths, or is - "serve it, don't double-click it" the right stance? Leaning no -- it is an anti-pattern - to support; the build hint message plus README note cover the real confusion. Revisit only - if users keep hitting it. \ No newline at end of file + "serve it, don't double-click it" the right stance? Leaning no. It is an anti-pattern + to support; the build hint message plus README note cover the real confusion. Revisit + only if users keep hitting it. \ No newline at end of file diff --git a/wherefore/log/2026-06-25-rename-to-wherefore.md b/wherefore/log/2026-06-25-rename-to-wherefore.md index 5274116..9b22801 100644 --- a/wherefore/log/2026-06-25-rename-to-wherefore.md +++ b/wherefore/log/2026-06-25-rename-to-wherefore.md @@ -14,7 +14,7 @@ superseded_date: Renamed the project from lore to wherefore after discovering that uselore.io is a paid closed-source AI knowledge-base product in the same Claude Code ecosystem. Trademark law turns on likelihood of confusion, not price, so being free and open-source is no -protection. Wherefore — the archaic word for "why" — fits the product concept precisely, +protection. Wherefore, the archaic word for "why", fits the product concept precisely, cleared npm and search, and provides a ready launch hook. ## Decisions / outcomes @@ -23,30 +23,31 @@ cleared npm and search, and provides a ready launch hook. - Plugin namespace and skill invocation prefix: wherefore. ## Why -Uselore.io is a direct competitor in the Claude Code ecosystem, making likelihood-of- -confusion a real risk. The rename is essentially free before the first npm publish; -waiting would break install strings and consumer configs. The lore/memory/myth naming -register is also overcrowded with competitors, so nothing was lost on differentiation. +Uselore.io is a direct competitor in the Claude Code ecosystem, making +likelihood-of-confusion a real risk. The rename is essentially free before the first npm +publish; waiting would break install strings and consumer configs. The lore/memory/myth +naming register is also overcrowded with competitors, so nothing was lost on +differentiation. -Wherefore is archaic English for "why" — "wherefore art thou" means "why are you", not +Wherefore is archaic English for "why": "wherefore art thou" means "why are you", not "where are you". That maps precisely to the product's purpose: a human-readable record of the *why* behind decisions, not an AI memory store. It cleared npm (404 page), returned clean on broader search, and the etymology is a concrete, memorable launch hook. Process lesson: always verify with `npm view ` or the npmjs page directly before -committing to a name — web search misses npm collisions (it missed whence). +committing to a name. Web search misses npm collisions (it missed whence). ## Alternatives considered -- **whence**: archaic "why", briefly the favorite for its brevity; rejected because the - npm name belongs to a prominent maintainer (Schlinkert), so the canonical package would +- whence: archaic "why", briefly the favorite for its brevity; rejected because the npm + name belongs to a prominent maintainer (Schlinkert), so the canonical package would never be ours. -- **mneme** (muse of memory): taken by Mneme HQ, whose product is nearly identical +- mneme (muse of memory): taken by Mneme HQ, whose product is nearly identical (version-controlled decision graphs, superseded decisions, no vector store, Claude Code - integration) — head-on collision. -- **iken** (from "I ken" = "I know"): free on npm, arguably best meaning-for-length; - rejected for ambiguous pronunciation and a crowded namespace (UK knowledge-management - company since 1992, plus an AI dev-environment outfit). -- **rell**: short and free but meaningless; clashes with Chromia's Rell language. + integration), a head-on collision. +- iken (from "I ken" = "I know"): free on npm, arguably best meaning-for-length; rejected + for ambiguous pronunciation and a crowded namespace (UK knowledge-management company + since 1992, plus an AI dev-environment outfit). +- rell: short and free but meaningless; clashes with Chromia's Rell language. - Earlier candidates (cairn, strata, throughline, vestige, mythos, saga, epos, quia, decisio, tome, crux): all taken, trademark-blocked, or sitting on a direct competitor. diff --git a/wherefore/log/2026-06-25-todo-list-out-of-scope.md b/wherefore/log/2026-06-25-todo-list-out-of-scope.md index ba00a7b..8e4a8e5 100644 --- a/wherefore/log/2026-06-25-todo-list-out-of-scope.md +++ b/wherefore/log/2026-06-25-todo-list-out-of-scope.md @@ -11,17 +11,17 @@ superseded_date: --- ## Summary -The team considered adding a to-do list feature to the plugin but decided against it. Wherefore's value is in capturing *why* decisions were made and surfacing open questions -- a task manager is a different product. +The team considered adding a to-do list feature to the plugin but decided against it. Wherefore's value is in capturing *why* decisions were made and surfacing open questions. A task manager is a different product. ## Decisions / outcomes - No to-do list feature will be built. - The plugin's scope stays narrowly focused on decision capture (why) and open question tracking. ## Why -To-do list tools are abundant and commoditized -- shipping another one adds no unique value. Wherefore is differentiated precisely because it is not a task manager: it captures rationale and open questions, not action items. Expanding into task management would dilute that identity and compete on a crowded axis. +To-do list tools are abundant and commoditized. Shipping another one adds no unique value. Wherefore is differentiated precisely because it is not a task manager: it captures rationale and open questions, not action items. Expanding into task management would dilute that identity and compete on a crowded axis. ## Alternatives considered -- Adding a lightweight to-do list alongside the wherefore log -- rejected because the feature is out of scope and the market is saturated. +- Adding a lightweight to-do list alongside the wherefore log. Rejected because the feature is out of scope and the market is saturated. ## Open questions / follow-ups - None. \ No newline at end of file diff --git a/wherefore/log/2026-06-25-underscore-frontmatter-keys.md b/wherefore/log/2026-06-25-underscore-frontmatter-keys.md index 8945915..2786f20 100644 --- a/wherefore/log/2026-06-25-underscore-frontmatter-keys.md +++ b/wherefore/log/2026-06-25-underscore-frontmatter-keys.md @@ -19,7 +19,7 @@ Wherefore frontmatter had a split convention: log entries used hyphenated keys ( - Existing data files were migrated (key names only, values unchanged) with a backup and file-count check to prevent loss. ## Why -The dashboard schema already used underscore, so the log files were already the odd one out -- and the mismatch was actively causing supersession links to be silently dropped. Underscore is the safer YAML/templating choice: hyphenated keys are valid YAML but cannot be accessed as bare identifiers in most templating languages and trip some parsers. The migration was done while the data set is small and entirely team-owned; once other projects have wherefore directories full of entries, renaming a frontmatter key becomes a breaking migration requiring a tool. +The dashboard schema already used underscore, so the log files were already the odd one out, and the mismatch was actively causing supersession links to be silently dropped. Underscore is the safer YAML/templating choice: hyphenated keys are valid YAML but cannot be accessed as bare identifiers in most templating languages and trip some parsers. The migration was done while the data set is small and entirely team-owned; once other projects have wherefore directories full of entries, renaming a frontmatter key becomes a breaking migration requiring a tool. ## Alternatives considered - Hyphenated keys everywhere: rejected because content.config.ts would have needed to change and hyphenated keys cause subtle failures in templating. diff --git a/wherefore/log/2026-06-25-visual-identity.md b/wherefore/log/2026-06-25-visual-identity.md index 8d7a12c..7f211cd 100644 --- a/wherefore/log/2026-06-25-visual-identity.md +++ b/wherefore/log/2026-06-25-visual-identity.md @@ -26,7 +26,7 @@ blinking cursor). Palette carried over from the dashboard and personal site. The terminal caret was too visually busy next to the three-dot mark. The decisive constraint was favicon size: the dot mark drawn as geometry survives to 16px, which a nine-letter wordmark in a mono font never could. Moving to a clean grotesk makes the product read as a -settled tool rather than a hacker sketch. The "because" operator is semantically precise -- +settled tool rather than a hacker sketch. The "because" operator is semantically precise: wherefore records the reasons behind decisions. ## Alternatives considered diff --git a/wherefore/questions/Q-001.md b/wherefore/questions/Q-001.md index a01312b..3d700e0 100644 --- a/wherefore/questions/Q-001.md +++ b/wherefore/questions/Q-001.md @@ -1,6 +1,6 @@ --- id: Q-001 -question: Will Astro build cleanly with content base and output dir both outside the Astro project root? +question: "Will Astro build cleanly with content base and output dir both outside the Astro project root?" status: open areas: [dashboard] asked_date: 2026-06-24 diff --git a/wherefore/questions/Q-002.md b/wherefore/questions/Q-002.md index 7f4fb3f..ee9d58e 100644 --- a/wherefore/questions/Q-002.md +++ b/wherefore/questions/Q-002.md @@ -1,6 +1,6 @@ --- id: Q-002 -question: When a second package lands, switch to prefixed release tags and promote to npm workspaces? +question: "When a second package lands, switch to prefixed release tags and promote to npm workspaces?" status: open areas: [repo-structure] asked_date: 2026-06-24 diff --git a/wherefore/questions/Q-003.md b/wherefore/questions/Q-003.md index 0027f48..73e66ed 100644 --- a/wherefore/questions/Q-003.md +++ b/wherefore/questions/Q-003.md @@ -1,6 +1,6 @@ --- id: Q-003 -question: Should the build-tool plan doc live inside the package as its design record? +question: "Should the build-tool plan doc live inside the package as its design record?" status: open areas: [dashboard, repo-structure] asked_date: 2026-06-24 diff --git a/wherefore/questions/Q-004.md b/wherefore/questions/Q-004.md index fea36e3..74d30f8 100644 --- a/wherefore/questions/Q-004.md +++ b/wherefore/questions/Q-004.md @@ -1,6 +1,6 @@ --- id: Q-004 -question: Resolve the path-filter and required-check interaction before enabling branch protection. +question: "Resolve the path-filter and required-check interaction before enabling branch protection." status: open areas: [repo-structure] asked_date: 2026-06-24 diff --git a/wherefore/questions/Q-005.md b/wherefore/questions/Q-005.md index 4d3629b..49ef612 100644 --- a/wherefore/questions/Q-005.md +++ b/wherefore/questions/Q-005.md @@ -1,10 +1,10 @@ --- id: Q-005 -question: Should the built site support file:// viewing via relative asset paths, or is "serve it, don't double-click it" the right stance? +question: "Should the built site support file:// viewing via relative asset paths, or is \"serve it, don't double-click it\" the right stance?" status: resolved areas: [dashboard] asked_date: 2026-06-25 asked_slug: 2026-06-25-npm-asset-scope -resolution: Do not support file:// viewing; keep absolute asset paths and fix user confusion via README and a build-time hint. +resolution: "Do not support file:// viewing; keep absolute asset paths and fix user confusion via README and a build-time hint." resolution_slug: 2026-06-25-no-file-url-serving --- \ No newline at end of file diff --git a/wherefore/questions/Q-006.md b/wherefore/questions/Q-006.md index b6d3b83..4b543cd 100644 --- a/wherefore/questions/Q-006.md +++ b/wherefore/questions/Q-006.md @@ -1,6 +1,6 @@ --- id: Q-006 -question: If cross-tool usage shows weaker models mangling multi-file mutations, should we add an MCP server wrapper? +question: "If cross-tool usage shows weaker models mangling multi-file mutations, should we add an MCP server wrapper?" status: open areas: [plugin] asked_date: 2026-06-25 diff --git a/wherefore/questions/Q-007.md b/wherefore/questions/Q-007.md index 119d032..d0406e7 100644 --- a/wherefore/questions/Q-007.md +++ b/wherefore/questions/Q-007.md @@ -1,6 +1,6 @@ --- id: Q-007 -question: Are there other latent schema/writer mismatches beyond the underscore key fix? +question: "Are there other latent schema/writer mismatches beyond the underscore key fix?" status: open areas: [dashboard] asked_date: 2026-06-25 diff --git a/wherefore/topics.md b/wherefore/topics.md index df090b3..251880d 100644 --- a/wherefore/topics.md +++ b/wherefore/topics.md @@ -4,22 +4,22 @@ Controlled tag vocabulary for this project's wherefore log. Two facets: Areas (w of the product) and Topics (cross-cutting concerns). Keep these coarse and stable. ## Areas -- plugin -- the Claude Code plugin: skills and commands -- dashboard -- the wherefore-dashboard build tool that renders wherefore/ as a static site -- branding -- product naming and how it is positioned -- repo-structure -- repository layout, packaging, and CI +- plugin: the Claude Code plugin: skills and commands +- dashboard: the wherefore-dashboard build tool that renders wherefore/ as a static site +- branding: product naming and how it is positioned +- repo-structure: repository layout, packaging, and CI ## Topics -- supersession -- the decision lifecycle: retiring or replacing past decisions -- data-model -- frontmatter shape, status fields, schema -- positioning -- how the product is framed against alternatives -- naming -- names of the product, skills, directories -- distribution -- how the dashboard reaches consuming projects -- publishing -- npm packaging and release mechanics -- ci -- continuous integration and workflows -- ui -- dashboard rendering and pages -- docs -- documentation decisions -- skill-structure -- how skills are split and organized -- build -- build pipeline and Astro integration -- visual-identity -- logo, wordmark, palette, and brand asset decisions -- cross-tool -- compatibility with non-Claude agents (Codex, Copilot, Cursor, Gemini, MCP) +- supersession: the decision lifecycle: retiring or replacing past decisions +- data-model: frontmatter shape, status fields, schema +- positioning: how the product is framed against alternatives +- naming: names of the product, skills, directories +- distribution: how the dashboard reaches consuming projects +- publishing: npm packaging and release mechanics +- ci: continuous integration and workflows +- ui: dashboard rendering and pages +- docs: documentation decisions +- skill-structure: how skills are split and organized +- build: build pipeline and Astro integration +- visual-identity: logo, wordmark, palette, and brand asset decisions +- cross-tool: compatibility with non-Claude agents (Codex, Copilot, Cursor, Gemini, MCP)