diff --git a/.cursor/rules/llm-wiki.mdc b/.cursor/rules/llm-wiki.mdc new file mode 100644 index 0000000..df74f47 --- /dev/null +++ b/.cursor/rules/llm-wiki.mdc @@ -0,0 +1,18 @@ +--- +description: LLM Wiki — read the project wiki's SCHEMA.md before any wiki operation +globs: + - "* wiki/**" +alwaysApply: false +--- + +# LLM Wiki + +This project's Obsidian vault is **` wiki/`** (repository folder name + space + `wiki`). + +Before creating, updating, or querying wiki pages, read the vault's `SCHEMA.md` for conventions. + +The vault uses `[[wikilinks]]` for internal links. Every page has YAML frontmatter. + +When the user says "ingest", "add to wiki", "lint wiki", or "query wiki", follow the workflows in SCHEMA.md. + +After significant work sessions, suggest filing key decisions and learnings into the wiki (ADRs in `decisions/`, runbooks in `guides/`). diff --git a/WIKI.md b/WIKI.md new file mode 100644 index 0000000..9a5c479 --- /dev/null +++ b/WIKI.md @@ -0,0 +1,14 @@ +# Where is the LLM wiki? + +The Obsidian vault is **not** a folder named `wiki`. + +It lives at: + +**` wiki/`** + +There is a **space** between the repo name and `wiki` (project wiki naming rule: *repository folder name* + space + `wiki`). + +- **In Obsidian:** *Open folder as vault* → choose the ` wiki` directory inside this repo. +- **In your editor / Explorer:** expand the repo root and look for **` wiki`** (not `wiki` alone). + +Start here: **` wiki/SCHEMA.md`**. diff --git a/loops wiki/.obsidian/app.json b/loops wiki/.obsidian/app.json new file mode 100644 index 0000000..49fefa6 --- /dev/null +++ b/loops wiki/.obsidian/app.json @@ -0,0 +1,9 @@ +{ + "useMarkdownLinks": false, + "newLinkFormat": "shortest", + "strictLineBreaks": true, + "attachmentFolderPath": "assets", + "showFrontmatter": true, + "readableLineLength": true, + "defaultViewMode": "preview" +} diff --git a/loops wiki/SCHEMA.md b/loops wiki/SCHEMA.md new file mode 100644 index 0000000..43bdd3e --- /dev/null +++ b/loops wiki/SCHEMA.md @@ -0,0 +1,152 @@ +# Wiki Schema + +> This file tells the LLM how to maintain this wiki. Read it at the start of every session that touches wiki pages. + +## Project + +- **Name**: +- **Domain**: + +## Directory structure + +The vault folder at the project root is **` wiki/`** (repository folder basename + space + `wiki`) — not bare `wiki/`. + +``` + wiki/ +├── SCHEMA.md ← you are here (LLM instructions) +├── index.md ← content catalog, organized by type +├── log.md ← chronological operations log +├── sources/ ← summaries of ingested documents +├── entities/ ← concrete things (tools, services, APIs, tables, configs) +├── concepts/ ← patterns, principles, architectural ideas +├── decisions/ ← architecture decision records (ADRs) +├── guides/ ← how-tos, runbooks, procedures +├── memories/ ← session-memory mirrors / archives +└── assets/ ← images, diagrams, attachments +``` + +## Page conventions + +### Filenames + +- **Kebab-case**, lowercase: `api-rate-limiting.md`, `postgres-connection-pool.md` +- Singular nouns for entities: `redis-cache.md` not `redis-caches.md` +- Verb-noun for guides: `deploy-to-production.md`, `rotate-api-keys.md` +- Decisions use numbered prefix: `0001-use-postgres-over-mysql.md` + +### Frontmatter + +Every page MUST have YAML frontmatter: + +```yaml +--- +title: Human-Readable Page Title +type: source | entity | concept | decision | guide +created: YYYY-MM-DD +updated: YYYY-MM-DD +tags: [relevant, tags] +aliases: [alternate-name, abbreviation] +sources: ["[[source-page]]"] +status: active | draft | superseded | archived +--- +``` + +### Links + +Use Obsidian-style wikilinks exclusively: + +- `[[page-name]]` for standard links +- `[[page-name|display text]]` for aliased links +- `[[page-name#section]]` for section links +- Never use markdown-style `[text](url)` for internal wiki links (reserve for external URLs) + +### Page structure + +Every page follows this skeleton: + +```markdown +--- +(frontmatter) +--- + +# Title + +One-paragraph summary of what this page covers. + +## Content sections +(varies by page type) + +## Related +- [[linked-page-1]] +- [[linked-page-2]] +``` + +## Page types + +### Source (`sources/`) + +Summary of an ingested document, article, file, or conversation. + +- **Key points** (bulleted takeaways) +- **Detailed notes** +- **Entities mentioned** — `[[wikilinks]]` +- **Concepts discussed** — `[[wikilinks]]` + +### Entity (`entities/`) + +A concrete thing: tool, service, API, library, database, config. + +- **What it is** / **How it's used in this project** / **Key details** / **Related** + +### Concept (`concepts/`) + +A pattern, principle, or architectural idea. + +- **Definition** / **Application here** / **Tradeoffs** / **Related** + +### Decision (`decisions/`) + +ADR. Filename: `NNNN-short-title.md`. + +- **Status** / **Context** / **Decision** / **Consequences** / **Related** + +### Guide (`guides/`) + +How-to or runbook. + +- **Prerequisites** / **Steps** / **Troubleshooting** / **Related** + +## Operations + +### Obsidian (human viewer) + +Open the folder **` wiki/`** as a vault (Obsidian → Open folder as vault). Graph view and backlinks work with wikilinks. + +### Ingest + +When the user provides a new source: create `sources/…`, update entities/concepts/decisions/guides, refresh `index.md`, append `log.md`. + +### Ingest existing docs + +Migrate from repo **`docs/`** in batches; synthesize; do **not** delete original `docs/` without human sign-off. + +### Query + +Read `index.md`, then relevant pages; answer with `[[wikilinks]]`; offer to file synthesis as new pages. + +### Lint + +Orphans, dead links, index drift, stale frontmatter, thin pages — report as checklist; fix with user approval. + +## Style rules + +- Clear, direct prose. Prefer concrete paths, commands, and versions. +- Use project terminology consistently. +- Update `updated` in frontmatter when editing a page. + +## Relationship to other project files + +- **`docs/`**: Raw documentation; ingest into `sources/` + derived pages. Binaries stay in `docs/`. +- **AI_SESSION_MEMORY.md**: Session breadcrumbs; wiki is compiled long-form knowledge. +- **AI_RUNBOOK.md** (if present): Operations; may become `guides/` pages. +- **AGENTS.md**: Agent index at repo root; complements this SCHEMA. diff --git a/loops wiki/index.md b/loops wiki/index.md new file mode 100644 index 0000000..31ae829 --- /dev/null +++ b/loops wiki/index.md @@ -0,0 +1,46 @@ +--- +title: Wiki Index +type: index +created: 2026-07-29 +updated: 2026-07-29 +--- + +# Wiki + +> Content catalog. The LLM reads this first when answering queries. Conventions: [[SCHEMA]]. + +## Sources + +| Page | Source | Ingested | +|------|--------|----------| +| _(none yet)_ | | | + +## Entities + +| Page | What it is | +|------|-----------| +| _(none yet)_ | | + +## Concepts + +| Page | Idea | +|------|------| +| _(none yet)_ | | + +## Decisions + +| Page | Decision | +|------|----------| +| _(none yet)_ | | + +## Guides + +| Page | How to | +|------|--------| +| _(none yet)_ | | + +## Memories + +| Page | Purpose | +|------|---------| +| _(none yet)_ | | diff --git a/loops wiki/log.md b/loops wiki/log.md new file mode 100644 index 0000000..8fbdb43 --- /dev/null +++ b/loops wiki/log.md @@ -0,0 +1,20 @@ +--- +title: Wiki Log +type: log +created: 2026-07-29 +updated: 2026-07-29 +--- + +# Wiki Log + +> Chronological record of wiki operations. Append-only. +> +> Format: `## [YYYY-MM-DD] verb | Subject` +> +> Verbs: `ingest`, `query`, `lint`, `update`, `create`, `migrate`, `session` +> +> Parseable: `grep "^## \[" log.md | tail -10` + +## [2026-07-29] create | Wiki bootstrapped + +Initial vault created by my-robot bootstrap (SCHEMA, index, log, folder layout, Obsidian settings). Ready for ingest from `docs/` or new sources.