@alekra1/llm-wiki 1.0.0

package/.cursorrules

@@ -0,0 +1,12 @@
+# Agent instructions
+
+This project uses an LLM wiki at `./wiki/` as its living context layer.
+
+**On session start:** read `wiki/HOWTO.md`, `wiki/index.md`, `wiki/_active/now.md`,
+and recent entries from `wiki/log.md`.
+
+**While working:** update the wiki per `wiki/HOWTO.md`. Use supersession, not deletion,
+for contradictions. Add a `log.md` entry for each wiki change.
+
+**On session end:** run the lint checklist from `wiki/HOWTO.md §Lint`, propose prunes
+to the user, apply on approval, and append a session summary to `wiki/log.md`.

package/AGENTS.md

@@ -0,0 +1,16 @@
+# Agent instructions
+
+This project uses an LLM wiki at `./wiki/` as its living context layer.
+
+**On session start:** read `wiki/_snapshot.md` first (fast bootstrap), then `wiki/HOWTO.md`,
+`wiki/index.md`, `wiki/_active/now.md`, and recent entries from `wiki/log.md`.
+
+**While working:** update the wiki per `wiki/HOWTO.md`. Use supersession, not deletion,
+for contradictions. Add a `log.md` entry for each wiki change.
+
+**On session end:** rewrite `wiki/_snapshot.md` to reflect current state, offer to run
+the lint checklist (`/wiki-lint`), apply approved changes, and append a session summary
+to `wiki/log.md`.
+
+**Slash commands** (Claude Code): `/wiki-update` — write a wiki entry; `/wiki-lint` — run
+the lint checklist; `/wiki-snapshot` — refresh the snapshot mid-session.

package/CLAUDE.md

@@ -0,0 +1,21 @@
+# Agent instructions
+
+This project uses an LLM wiki at `./wiki/` as its living context layer.
+
+**On session start:** read `wiki/_snapshot.md` first (fast bootstrap), then
+`wiki/_active/now.md` and recent entries from `wiki/log.md`. If unfamiliar with the
+wiki conventions, also read `wiki/HOWTO.md`. Drill into other pages only as needed.
+
+**While working:** update the wiki per `wiki/HOWTO.md`. Use supersession, not deletion,
+for contradictions. Add a `log.md` entry for each wiki change.
+
+**On session end:** rewrite `wiki/_snapshot.md` to reflect current state if anything changed this session. Run `/wiki-lint` only when the user asks for it.
+
+**Slash commands**: `/wiki-update` — write a wiki entry; `/wiki-lint` — run the lint
+checklist; `/wiki-snapshot` — refresh the snapshot mid-session. Hooks in
+`.claude/settings.json` automate the session-start reads and session-end prompt.
+
+**If you are a subagent** (spawned via API, orchestration tool, or CI — not an
+interactive CC session): hooks will not fire. Treat these instructions as your hooks.
+Read `wiki/_snapshot.md` at the start of your first response. Write updates to the wiki
+before your final response. Append a `log.md` entry for any wiki change made.

package/GEMINI.md

@@ -0,0 +1,12 @@
+# Agent instructions
+
+This project uses an LLM wiki at `./wiki/` as its living context layer.
+
+**On session start:** read `wiki/HOWTO.md`, `wiki/index.md`, `wiki/_active/now.md`,
+and recent entries from `wiki/log.md`.
+
+**While working:** update the wiki per `wiki/HOWTO.md`. Use supersession, not deletion,
+for contradictions. Add a `log.md` entry for each wiki change.
+
+**On session end:** run the lint checklist from `wiki/HOWTO.md §Lint`, propose prunes
+to the user, apply on approval, and append a session summary to `wiki/log.md`.

package/README.md

@@ -0,0 +1,48 @@
+# llm-wiki
+
+A markdown wiki template that gives LLM agents persistent, cross-session memory. Copy it into any project — agents read and write `wiki/` as a living brain that survives context resets and provider switches.
+
+## Install
+
+```bash
+npx @alekra1/llm-wiki
+```
+
+This copies `wiki/` into your project, creates or appends to `CLAUDE.md`, and adds provider files (`AGENTS.md`, `GEMINI.md`, `.cursorrules`) if they don't exist.
+
+Then install the Claude Code plugin for slash commands:
+```
+/plugin marketplace add Alekra1/llm-wiki
+/plugin install wiki@llm-wiki
+```
+
+## What's included
+
+| File/Dir | Purpose |
+|---|---|
+| `wiki/` | The wiki: snapshot, active tasks, decisions, preferences, pitfalls, workflows |
+| `CLAUDE.md` | Agent instructions for Claude Code |
+| `AGENTS.md` | Same for OpenAI Agents / Codex |
+| `GEMINI.md` | Same for Gemini |
+| `.cursorrules` | Same for Cursor |
+| `.claude/` | CC plugin: SessionStart hook + `/wiki-lint`, `/wiki-update`, `/wiki-snapshot` |
+
+## How it works
+
+On session start, the agent reads `wiki/_snapshot.md` (~300 tokens, ~30 seconds) and picks up exactly where the last session ended. No summaries to maintain — the wiki is the memory.
+
+Agents write to the wiki as they work: decisions in `wiki/decisions/`, preferences in `wiki/preferences/`, active tasks in `wiki/_active/`. Every change gets a line in `wiki/log.md`.
+
+Read `wiki/HOWTO.md` for conventions.
+
+## Slash commands (Claude Code plugin)
+
+| Command | What it does |
+|---|---|
+| `/wiki-update` | Write a new wiki entry |
+| `/wiki-lint` | Run the wiki health checklist |
+| `/wiki-snapshot` | Refresh the snapshot mid-session |
+
+## Provider support
+
+Works with any LLM that can read files. Entry-point files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`) contain identical instructions in each provider's expected format.

package/bin/setup.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const DEST = process.cwd();
+
+const G = '\x1b[32m';
+const Y = '\x1b[33m';
+const R = '\x1b[0m';
+
+function copyRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    entry.isDirectory() ? copyRecursive(s, d) : fs.copyFileSync(s, d);
+  }
+}
+
+// 1. Copy wiki/
+const wikiDest = path.join(DEST, 'wiki');
+if (fs.existsSync(wikiDest)) {
+  console.log(`· wiki/ already exists — skipping (delete to reinstall)`);
+} else {
+  copyRecursive(path.join(PKG_ROOT, 'wiki'), wikiDest);
+  console.log(`${G}✓${R} Created wiki/`);
+}
+
+// 2. Handle CLAUDE.md — append if exists, create if not
+const WIKI_BLOCK = `
+# Wiki
+
+This project uses an LLM wiki at \`./wiki/\` as its living context layer.
+
+**On session start:** read \`wiki/_snapshot.md\` first (fast bootstrap), then
+\`wiki/_active/now.md\` and recent entries from \`wiki/log.md\`. If unfamiliar
+with the wiki conventions, also read \`wiki/HOWTO.md\`. Drill into other pages
+only as needed.
+
+**While working:** update the wiki per \`wiki/HOWTO.md\`. Use supersession, not
+deletion, for contradictions. Add a \`log.md\` entry for each wiki change.
+
+**On session end:** rewrite \`wiki/_snapshot.md\` to reflect current state if
+anything changed this session.
+
+**If you are a subagent** (spawned via API, orchestration tool, or CI — not an
+interactive CC session): hooks will not fire. Treat these instructions as your
+hooks. Read \`wiki/_snapshot.md\` at the start of your first response. Write
+updates to the wiki before your final response. Append a \`log.md\` entry for
+any wiki change made.
+`;
+
+const claudePath = path.join(DEST, 'CLAUDE.md');
+if (fs.existsSync(claudePath)) {
+  const existing = fs.readFileSync(claudePath, 'utf8');
+  if (existing.includes('wiki/_snapshot.md')) {
+    console.log(`· CLAUDE.md already has wiki instructions — skipping`);
+  } else {
+    fs.appendFileSync(claudePath, '\n---\n' + WIKI_BLOCK);
+    console.log(`${G}✓${R} Appended wiki instructions to CLAUDE.md`);
+  }
+} else {
+  fs.writeFileSync(claudePath, WIKI_BLOCK.trimStart());
+  console.log(`${G}✓${R} Created CLAUDE.md`);
+}
+
+// 3. Optional provider files — copy only if absent
+for (const file of ['AGENTS.md', 'GEMINI.md', '.cursorrules']) {
+  const dest = path.join(DEST, file);
+  const src = path.join(PKG_ROOT, file);
+  if (fs.existsSync(src) && !fs.existsSync(dest)) {
+    fs.copyFileSync(src, dest);
+    console.log(`${G}✓${R} Created ${file}`);
+  } else if (fs.existsSync(dest)) {
+    console.log(`· ${file} already exists — skipping`);
+  }
+}
+
+console.log('');
+console.log('Done. Next steps:');
+console.log('  1. Fill in wiki/_snapshot.md with your project state');
+console.log('  2. Start a Claude Code session — wiki bootstraps automatically');
+console.log('');
+console.log(`${Y}Tip:${R} install the CC plugin for slash commands (/wiki-lint, /wiki-update, /wiki-snapshot):`);
+console.log('  /plugin marketplace add Alekra1/llm-wiki');
+console.log('  /plugin install wiki@llm-wiki');
+console.log('');
+console.log(`Re-run anytime: npx @alekra1/llm-wiki`);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@alekra1/llm-wiki",
+  "version": "1.0.0",
+  "description": "Markdown wiki template for LLM agent persistent memory. Gives agents cross-session, cross-provider memory.",
+  "bin": {
+    "llm-wiki": "bin/setup.js"
+  },
+  "files": [
+    "bin/",
+    "wiki/",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    ".cursorrules"
+  ],
+  "keywords": [
+    "llm",
+    "claude",
+    "agents",
+    "wiki",
+    "memory",
+    "context",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alekra1/llm-wiki.git"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/wiki/EXAMPLES.md

@@ -0,0 +1,133 @@
+# Examples
+
+Canonical format examples for each wiki page type.
+Copy these as starting points; replace the placeholder content.
+
+---
+
+## Decision page
+
+File: `decisions/auth-strategy.md`
+
+    ---
+    type: decision
+    last_confirmed: 2026-05-11
+    ---
+
+    # Auth strategy
+
+    - 2026-04-15 — chose JWT (anticipated microservices split; stateless tokens fit that model)
+    - 2026-05-11 [SUPERSEDES above] — reverted to sessions + Redis. Reason: microservices split
+      was deprioritised; monolith for the foreseeable future. JWT added complexity (key rotation,
+      revocation) without benefit. Cookies + Redis are simpler and fully sufficient.
+
+---
+
+## Preference page
+
+File: `preferences/tools.md`
+
+    ---
+    type: preference
+    last_confirmed: 2026-05-11
+    ---
+
+    # Tools preferences
+
+    - 2026-05-11 — use pnpm as package manager (faster installs, consistent lockfiles)
+    - 2026-05-20 [SUPERSEDES above] — switched to bun. Reason: bun's runtime speed matters
+      for this project's test suite; pnpm lockfile had repeated sync issues across machines.
+
+---
+
+## Workflow page
+
+File: `workflows/deploy.md`
+
+    ---
+    type: workflow
+    last_confirmed: 2026-05-11
+    ---
+
+    # Deploy workflow
+
+    1. Run `pnpm test` — confirm all passing.
+    2. If schema changed: run `pnpm db:migrate` (check `git diff HEAD~1 -- migrations/`).
+    3. Push to `main` — CI deploys to staging automatically.
+    4. Verify staging at staging.example.com.
+    5. Tag release: `git tag v<semver> && git push --tags`.
+    6. CI promotes to production on tags automatically.
+
+    Pitfall: step 2 is easy to skip when no migration file is obviously new. Always check.
+
+---
+
+## Pitfall page
+
+File: `pitfalls/build.md`
+
+    ---
+    type: pitfall
+    last_confirmed: 2026-05-11
+    ---
+
+    # Build failures
+
+    ## Schema not migrated before build
+
+    Symptom: build fails with "column X does not exist"
+    Fix: `pnpm db:migrate` then retry build
+    Root cause: type-check step queries the live schema; stale schema causes type errors.
+
+    ## Port conflict on dev start
+
+    Symptom: `EADDRINUSE :::3000`
+    Fix: `lsof -ti:3000 | xargs kill` then restart
+    Root cause: prior dev server not cleanly stopped.
+
+---
+
+## Log entries
+
+File: `log.md` (append-only)
+
+    ## [2026-05-11 10:30] init | wiki initialized
+
+    Starting wiki. Populated starter pages. Active task: set up authentication flow.
+
+    ## [2026-05-11 14:22] decision | reverted JWT to sessions
+
+    See decisions/auth-strategy.md for full reasoning trace.
+
+    ## [2026-05-11 17:45] pitfall | build fails when migrations not applied
+
+    Added entry to pitfalls/build.md.
+
+    ## [2026-05-11 18:00] session-end | lint clean, 0 issues
+
+    No changes applied. Wiki state confirmed current.
+
+---
+
+## Active task page
+
+File: `_active/now.md`
+
+    ---
+    type: active
+    last_confirmed: 2026-05-11
+    ---
+
+    # Current work
+
+    ## Active task
+
+    Implementing the password reset flow. Email sending works; token validation endpoint
+    in progress. Blocked on: deciding token expiry (1h vs 24h — see open-questions.md).
+
+    ## Context for next session
+
+    - File: `src/auth/reset.ts` — main implementation
+    - File: `src/email/templates/reset.html` — email template, done
+    - Decision needed: token expiry duration (open question)
+    - Do not restart the work on JWT — that decision is settled (see decisions/auth-strategy.md)

package/wiki/HOWTO.md

@@ -0,0 +1,194 @@
+---
+purpose: agent-facing schema — read this before any other wiki file
+version: 1.0
+---
+
+# Wiki HOWTO
+
+This wiki is the project's living context layer — preferences, decisions, workflows,
+pitfalls, and active state accumulated across sessions and providers.
+
+You maintain it. The human reads it. Read this file first; follow its rules exactly.
+
+---
+
+## Session start
+
+Read in this order on every new session:
+
+1. `wiki/_snapshot.md` — compressed current-state summary; read this first for fast bootstrap
+2. `wiki/index.md` — catalog of all pages; find what is relevant to the current work
+3. `wiki/_active/now.md` — current task, blockers, in-flight state
+4. Last 10 entries of `wiki/log.md` — what happened recently
+
+Drill into other pages only when relevant to the task at hand. The index is your map.
+
+---
+
+## During the session: when to write
+
+Write to the wiki for **rules** — facts expected to hold across future sessions.
+Do NOT write **observations** (one-off events, current conversation state) unless they
+recur or the user explicitly elevates them.
+
+| Signal | Where to write |
+|--------|----------------|
+| User states a preference ("I prefer X") | `preferences/` |
+| A technical or design decision is made | `decisions/<topic>.md` |
+| A workflow repeats more than once | `workflows/<topic>.md` |
+| Something breaks and the fix is understood | `pitfalls/<area>.md` |
+| Architecture insight that took effort to derive | `architecture/` |
+| Current task / in-flight state changes | `_active/now.md` |
+| Any of the above | also append to `log.md`; update `index.md` if new page |
+
+**preferences/ vs decisions/**: use `preferences/` for *how the agent should behave* (tone, verbosity, tool choices). Use `decisions/` for *what the project should do* (architecture, library choices, data model). When a toolchain choice affects both (e.g. "use pnpm"), write a `decisions/` entry as the primary source; only add a `preferences/` entry if it also changes agent behavior (e.g. always use pnpm in commands).
+
+**Closely related stack choices**: when a user states multiple related tech choices in one conversation (e.g. React + Vite + pnpm + Express), you may group them in a single `decisions/stack.md` rather than creating four thin files. The anti-bloat rule against `stack.md` applies to catch-all files that grow without discipline — a focused initial stack declaration is fine.
+
+---
+
+## The supersession rule (most important)
+
+When new knowledge **contradicts** existing knowledge, **never delete the old entry**.
+Append a dated revision block below it.
+
+The reasoning trace — why we changed our mind — is the most valuable part of this wiki.
+
+**Format:**
+
+```
+- YYYY-MM-DD — [original claim] ([original reasoning])
+- YYYY-MM-DD [SUPERSEDES above] — [new claim]. Reason: [why we changed].
+```
+
+Multiple supersessions stack chronologically. The most recent entry reflects current truth.
+Reading all entries shows how the project's thinking evolved.
+
+**Same-session supersession**: if the user changes their mind within the same session, write only the final decision. Do not write the initial choice and immediately supersede it — that produces noise. The log entry can note the change: "user revised during session from X to Y."
+
+**Read-before-write rule**: always read the current on-disk version of a file immediately before writing it — even if you read it earlier in the session. Another agent may have written it since. If the file now contains content you did not see, apply supersession rather than overwriting.
+
+---
+
+## Page format
+
+Every wiki page uses lightweight YAML frontmatter:
+
+```yaml
+---
+type: preference | decision | workflow | pitfall | architecture | active | snapshot
+supersedes: <optional: path to prior page if this replaces another entirely>
+---
+```
+
+---
+
+## Index discipline
+
+`index.md` is the canonical catalog. Every page must appear there.
+
+- When you **create** a page: add it to `index.md` immediately.
+- When you **rename or delete** a page: update `index.md` immediately.
+
+Format: `- [Page Title](relative/path.md) — one-line summary`
+
+**Excluded from index tracking** (do not list, do not flag as orphans during lint):
+- `wiki/README.md` — human-facing intro, not a content page
+- `wiki/HOWTO.md` and `wiki/EXAMPLES.md` — schema files, listed separately under §Schema
+- Any file named `EXAMPLE.md` — these are format templates, not content
+
+---
+
+## Log discipline
+
+`log.md` is append-only. Never edit or delete existing entries.
+Every wiki write gets a log entry.
+
+**Format:**
+
+```
+## [YYYY-MM-DD HH:MM] <type> | <short description>
+
+Optional 1-2 sentence detail if the change was complex.
+```
+
+`HH:MM` is approximate — use your best estimate of the current time, or omit and use `00:00` if unknown.
+
+Types: `init`, `preference`, `decision`, `workflow`, `pitfall`, `architecture`, `active`, `lint`, `session-end`
+
+The prefix `## [YYYY-MM-DD` makes entries grep-able:
+```
+grep "^## \[" wiki/log.md | tail -10
+```
+
+---
+
+## Snapshot discipline
+
+`_snapshot.md` is the L1 fast-bootstrap. Rewrite it at the end of every session.
+
+**What belongs in the snapshot** (keep it to one screen):
+- What the project is (one sentence)
+- Current phase and active task
+- Immediate next steps (3–5 ordered items)
+- Critical constraints a fresh agent must not forget (3–5 bullets)
+- Key open questions (link to `_active/open-questions.md` for detail)
+
+**Rules**:
+- Rewrite from scratch each time — do not append. It reflects current truth only.
+- No log-style history; that belongs in `log.md`.
+- If nothing changed this session, leave content as-is — git tracks when the file last changed.
+
+---
+
+## Lint (session end / on request)
+
+When asked to lint the wiki, run this checklist in order:
+
+1. **Orphans** — pages not listed in `index.md`. Propose: add to index or delete.
+2. **Stale pages** — pages whose content appears outdated relative to current project state. Propose: update or archive.
+3. **Contradictions** — pages in the same category making opposing claims without supersession. Propose: merge with supersession block.
+4. **Duplicates** — overlapping content across separate pages. Propose: merge into one.
+5. **Empty templates** — placeholder pages never filled in. Propose: fill or delete.
+6. **Stale active items** — items in `_active/` that appear resolved. Propose: remove or graduate to `decisions/` or `workflows/`.
+
+**Propose all changes. Apply only on user approval.**
+After lint: rewrite `_snapshot.md` to reflect current state, then append a `session-end` entry to `log.md`.
+
+---
+
+## Non-CC environments
+
+If slash commands (`/wiki-lint`, `/wiki-update`, `/wiki-snapshot`) are unavailable (Cursor, Gemini, Copilot, raw API), use these manual equivalents:
+
+- Instead of `/wiki-update`: "Update the wiki with this decision per wiki/HOWTO.md routing table."
+- Instead of `/wiki-lint`: "Run the 6-step lint checklist from wiki/HOWTO.md §Lint and report findings."
+- Instead of `/wiki-snapshot`: "Rewrite wiki/_snapshot.md to reflect current project state."
+
+Session-start and session-end hooks will not fire. The agent must follow the startup read sequence and end-of-session writes manually, guided by CLAUDE.md or AGENTS.md.
+
+---
+
+## Multi-agent safety
+
+The wiki is designed for **one agent with exclusive access**. Concurrent agents are unsafe because:
+- `decisions/` files: last writer silently overwrites; supersession rule requires reading before writing
+- `index.md`: stale-read/write-back race can silently delete other agents' entries
+- `log.md`: append-only; the only file safe for concurrent writes
+
+If multiple agents write to the wiki:
+1. Apply the **read-before-write rule** strictly — read the file immediately before writing it.
+2. Include an agent identifier in log entries: `[agent-A] decision | ...`
+3. If you detect a conflict in a decisions/ file, apply supersession rather than overwriting.
+
+---
+
+## Anti-bloat principles
+
+- Prefer editing existing pages over creating new ones.
+- One page per concept — never two pages on the same topic.
+- For `decisions/`: one file per discrete decision, named by noun (`decisions/orm.md`, `decisions/auth-strategy.md`). Do not create a catch-all `decisions/stack.md`.
+- `_active/` is volatile: prune aggressively; nothing stays there more than a few sessions.
+- When a blocker in `_active/now.md` resolves into a settled decision, remove it from the blockers list and create the corresponding `decisions/` page.
+- When unsure whether to write: if it won't matter in a month, skip it.
+- A page with many stacked supersessions is a candidate for a clean rewrite — propose it during lint.

package/wiki/README.md

@@ -0,0 +1,41 @@
+# Project Wiki
+
+This directory is the project's living knowledge base — its brain alongside the code body.
+
+It is maintained entirely by the LLM agent. **You do not need to edit it yourself.**
+Read it freely; let the agent write it.
+
+---
+
+## What's in here
+
+| Path | Purpose |
+|------|---------|
+| `HOWTO.md` | Agent schema — how the wiki is read, written, and linted |
+| `EXAMPLES.md` | Canonical format examples for each page type |
+| `index.md` | Catalog of all pages (agent-maintained) |
+| `log.md` | Chronological session log — append-only |
+| `preferences/` | Your preferences for communication, tools, and code style |
+| `workflows/` | How recurring tasks are done in this project |
+| `decisions/` | Technical and design decisions with full reasoning traces |
+| `pitfalls/` | Known failure modes and their fixes |
+| `architecture/` | Structural knowledge that takes effort to re-derive |
+| `_active/` | Current task and open questions — volatile, pruned often |
+
+---
+
+## How to adopt this in another project
+
+1. Copy this entire `wiki/` directory into your project's root.
+2. Copy the provider entry files from the repo root (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`) to your project's root.
+3. Clear the placeholder example content, keeping directory structure and frontmatter templates.
+4. Start a new session. The agent will read the entry file automatically and bootstrap from the wiki.
+
+---
+
+## What NOT to do
+
+- Don't manually edit `log.md` — it is append-only and the agent owns it.
+- Don't delete pages to "fix" outdated information — tell the agent; it uses supersession.
+- Don't store raw source documents here — the wiki holds synthesized knowledge only.
+- Don't write pages yourself — tell the agent what was decided and let it write the page.

package/wiki/_active/now.md

@@ -0,0 +1,19 @@
+---
+type: active
+---
+
+# Current work
+
+## Active task
+
+<!-- What are we working on right now? Be specific enough that a fresh agent
+     can pick up without re-explanation. Include file paths if relevant. -->
+
+## Blockers
+
+<!-- What is blocking progress? What decision is pending? -->
+
+## Context for next session
+
+<!-- Critical: what must a fresh agent know immediately to avoid going in the wrong direction?
+     Keep this to 3-5 bullet points. Details live in decisions/ and architecture/. -->

package/wiki/_active/open-questions.md

@@ -0,0 +1,12 @@
+---
+type: active
+---
+
+# Open questions
+
+Questions without answers yet. Graduate to `decisions/` once resolved.
+
+<!-- Format:
+- YYYY-MM-DD — [question] → status: open | investigating | resolved
+  [optional: relevant context or constraints]
+-->

package/wiki/_snapshot.md

@@ -0,0 +1,28 @@
+---
+type: snapshot
+---
+
+# Project snapshot
+
+<!-- Rewrite this entire file at the end of every session.
+     Keep it to one screen. This is the L1 fast-bootstrap: a fresh agent should read
+     this one file and have enough context to continue without reading anything else.
+     Fill in the real values below; delete these comments when done. -->
+
+**What**: <!-- one sentence: what is this project and what does it do? -->
+
+**Current phase**: <!-- e.g. "MVP in progress", "Phase 2 complete", "maintenance" -->
+
+**Active task**: <!-- the single thing being worked on right now -->
+
+**Immediate next steps** (in order):
+1. <!-- step 1 -->
+2. <!-- step 2 -->
+3. <!-- step 3 -->
+
+**Critical context**:
+- <!-- a key constraint, decision, or fact a fresh agent must not forget -->
+- <!-- another critical fact — keep to 3–5 bullets -->
+
+**Open questions** (see [_active/open-questions.md](_active/open-questions.md)):
+- <!-- unresolved question, or "None currently." -->

package/wiki/architecture/overview.md

@@ -0,0 +1,16 @@
+---
+type: architecture
+---
+
+# Architecture overview
+
+<!-- High-level description of the project's architecture.
+Updated as understanding deepens. Use supersession for significant changes.
+
+Suggested sections:
+- Tech stack (languages, frameworks, databases, infrastructure)
+- Main modules / services and their responsibilities
+- Key data flows
+- External dependencies and why they were chosen
+- What is intentionally NOT here (and why)
+-->

package/wiki/decisions/EXAMPLE.md

@@ -0,0 +1,13 @@
+---
+type: decision
+---
+
+# [Decision topic]
+
+<!-- One decision per file. Use the supersession format — never delete old entries.
+See wiki/EXAMPLES.md for a full worked example.
+
+Format:
+- YYYY-MM-DD — [decision made] ([reasoning])
+- YYYY-MM-DD [SUPERSEDES above] — [new decision]. Reason: [why changed].
+-->

package/wiki/index.md

@@ -0,0 +1,45 @@
+# Wiki index
+
+Catalog of all wiki pages. Agent-maintained — updated on every page create or rename.
+
+---
+
+## Schema
+
+- [HOWTO.md](HOWTO.md) — agent schema: how to read, write, and lint the wiki
+- [EXAMPLES.md](EXAMPLES.md) — canonical format examples for each page type
+
+## Snapshot
+
+- [_snapshot.md](_snapshot.md) — compressed current-state summary for fast session bootstrap
+
+## Preferences
+
+- [preferences/communication.md](preferences/communication.md) — tone, verbosity, and formatting preferences
+- [preferences/tools.md](preferences/tools.md) — package managers, shells, CLIs, and toolchain choices
+- [preferences/style.md](preferences/style.md) — code style and naming conventions
+
+## Workflows
+
+- [workflows/commit.md](workflows/commit.md) — commit message conventions
+
+## Decisions
+
+*(none yet — entries added as decisions are made)*
+
+## Pitfalls
+
+*(none yet — entries added as pitfalls are encountered and understood)*
+
+## Architecture
+
+- [architecture/overview.md](architecture/overview.md) — high-level architecture overview
+
+## Active
+
+- [_active/now.md](_active/now.md) — current task and blockers
+- [_active/open-questions.md](_active/open-questions.md) — open questions pending resolution
+
+## Log
+
+- [log.md](log.md) — chronological session log (append-only)

package/wiki/log.md

@@ -0,0 +1,14 @@
+# Session log
+
+Append-only. Never edit or delete existing entries.
+
+Format: `## [YYYY-MM-DD HH:MM] <type> | <description>`
+Types: `init`, `preference`, `decision`, `workflow`, `pitfall`, `architecture`, `active`, `lint`, `session-end`
+
+Grep recent: `grep "^## \[" wiki/log.md | tail -10`
+
+---
+
+## [YYYY-MM-DD HH:MM] init | wiki initialized
+
+Wiki structure created from llm-wiki template. Ready for project-specific content to be added as the project develops. Next session: read HOWTO.md and index.md to bootstrap.

package/wiki/pitfalls/EXAMPLE.md

@@ -0,0 +1,14 @@
+---
+type: pitfall
+---
+
+# [Area: build | tests | deploy | auth | ...]
+
+<!-- Group related pitfalls in one file by area. Format per pitfall:
+
+## [Short name for the failure mode]
+
+Symptom: [what you observe when it happens]
+Fix: [the command or action that resolves it]
+Root cause: [why it happens — helps recognize future variants]
+-->

package/wiki/preferences/communication.md

@@ -0,0 +1,12 @@
+---
+type: preference
+---
+
+# Communication preferences
+
+How the agent should communicate: tone, response length, formatting, etc.
+
+<!-- Add entries using the supersession format from wiki/EXAMPLES.md.
+Example:
+- 2026-05-11 — prefer terse responses; skip end-of-turn summaries; no emoji unless requested
+-->

package/wiki/preferences/style.md

@@ -0,0 +1,13 @@
+---
+type: preference
+---
+
+# Code style preferences
+
+Naming conventions, formatting rules, patterns to use or avoid.
+
+<!-- Add entries using the supersession format from wiki/EXAMPLES.md.
+Example:
+- 2026-05-11 — TypeScript strict mode; no `any`; explicit return types on public functions
+- 2026-05-11 — snake_case for database columns, camelCase for TypeScript identifiers
+-->

package/wiki/preferences/tools.md

@@ -0,0 +1,13 @@
+---
+type: preference
+---
+
+# Tools preferences
+
+Package managers, shells, CLIs, editors, and other toolchain choices.
+
+<!-- Add entries using the supersession format from wiki/EXAMPLES.md.
+Example:
+- 2026-05-11 — use bun as package manager and runtime (speed, built-in test runner)
+- 2026-05-11 — use fish shell in terminal sessions
+-->

package/wiki/workflows/commit.md

@@ -0,0 +1,16 @@
+---
+type: workflow
+---
+
+# Commit workflow
+
+How commits are structured and written in this project.
+
+<!-- Populate this with your project's conventions. Example below.
+
+- 2026-05-11 — conventional commits format: `<type>(<scope>): <description>`
+  Types: feat, fix, chore, refactor, docs, test
+  Example: `fix(auth): handle expired session tokens`
+  No emoji. Imperative present tense. Scope optional.
+  Each commit is a logical unit — squash fixups before merging.
+-->