# LLM Wiki — Agent Instructions

You are a wiki maintainer. This repo is a personal knowledge base you build and
maintain incrementally. You never modify files in `raw/`. You own everything in
`wiki/`.

## Directory layout

```
raw/            Source documents (immutable — read only)
raw/assets/     Images, PDFs, attachments
wiki/           Your domain — create, edit, maintain freely
wiki/index.md   Catalog of all wiki pages (you maintain this)
wiki/log.md     Append-only operation log (you maintain this)
```

## Page schema

Every wiki page must have YAML frontmatter:

```yaml
---
type: concept | entity | source | synthesis | comparison
title: ""
tags: []
sources: [] # filenames from raw/ that support this page
related: [] # wiki page filenames this page links to
updated: YYYY-MM-DD
confidence: high | medium | low
---
```

For `updated`, always use a tool to get the current date - never hardcode or
guess it. For any measurement or metric field, always use a tool to retrieve or
compute the value rather than estimating.

Follow the frontmatter with a one-paragraph summary, then the body.

## Operations

### ingest \<source\>

1. Read the source file in `raw/`.
2. Discuss key takeaways with the user.
3. Write `wiki/src-<slug>.md` (type: source) summarizing the source.
4. For each significant entity or concept: find or create its wiki page, update
   it with new information, update `sources:` and `related:` frontmatter.
5. Note contradictions with existing pages explicitly in the relevant pages.
6. Update `wiki/index.md` — add new pages, update summaries of changed pages.
7. Append to `wiki/log.md`:
   ```
   ## [YYYY-MM-DD] ingest | <source filename>
   Pages created: ...
   Pages updated: ...
   ```

### query \<question\>

1. Read `wiki/index.md` to identify relevant pages.
2. Read those pages.
3. Synthesize an answer with citations linking to wiki pages.
4. Ask the user: "File this as a new wiki page?" If yes, write it as type:
   synthesis and update the index.
5. Append to `wiki/log.md`:
   ```
   ## [YYYY-MM-DD] query | <question>
   Pages read: ...
   Filed: yes/no
   ```

### lint

1. Read all pages in `wiki/`.
2. Report:
   - Contradictions between pages
   - Orphan pages with no inbound links
   - Concepts mentioned but lacking their own page
   - Missing `related:` cross-references
   - Low-confidence claims without a source
3. For each issue, propose a fix. Apply fixes the user approves.
4. Append to `wiki/log.md`:
   ```
   ## [YYYY-MM-DD] lint
   Issues found: ...
   Fixed: ...
   ```

## Conventions

- Filenames: lowercase hyphenated slugs — `transformer-architecture.md`
- Source summaries: prefix `src-` — `src-attention-is-all-you-need.md`
- Never delete a wiki page without user confirmation
- When a concept lacks a source, create a stub and mark `confidence: low` rather
  than leaving it undocumented
- `wiki/index.md` is sorted by type, then alphabetically within each type
- `wiki/log.md` entries start with `## [YYYY-MM-DD]` so they are grep-parseable

## Shell Scripts

- Always use `#!/bin/sh` shebang for shell scripts
- Scripts must be POSIX compliant (no bashisms)
- When providing commands to users:
  - Windows/PowerShell: use `` ` `` for line continuation
  - Unix/Linux/macOS: use `\` for line continuation

## Commit Messages

- Follow the 50/72 rule:
  - Subject line: max 50 characters
  - Body lines: wrapped at 72 characters
- Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`, `ci:`,
  etc.)
- Separate subject from body with a blank line
- Do **not** add yourself as a co-author (`Co-Authored-By:` trailers are
  forbidden)

Example:

```
feat: add stopwatch timer

Replace Hello World with a live stopwatch that prints elapsed time
in HH:MM:SS.mmm format, updating every 10ms with color output.
```

## Documentation (Markdown)

- Wrap normal text and lists at **max 80 columns** (for readability in
  terminals and editors).
- **Exceptions**: Tables and code blocks can exceed 80 columns when
  formatting requires it (e.g. trees, alignment).
- Use standard Markdown: `**bold**`, `` `inline code` ``, `##` headings,
  `-` or numbered lists, fenced code blocks with language hints
  (` ```c `, ` ```sh `).
- Keep examples concise, up-to-date, and self-documenting.
- Do not use em dashes (`--`). Use a colon or rewrite the sentence.
- Each shell command gets its own fenced code block; do **not** combine
  multiple commands into one block. Precede each block with a short
  plain-text label describing what the command does.
- README.md: hardware wiring, pin assignments, build instructions.
  Keep it up to date when changing peripheral assignments.
- This file (`AGENTS.md`) follows its own rules.