Imported from spacecowboyian/shopscreen (docs/AGENTS.md). Install upstream with npx skills add spacecowboyian/shopscreen --skill docs. Copyright stays with the author.

Docs wiki: instructions for LLMs (and humans)

docs/ is ShopScreen's shared memory, a small wiki of plain markdown files in git. There's no server, no MCP, no database, and no tooling. You read files, edit files, and keep two bookkeeping files current.

Ian, Kel, and whatever LLMs they use all work in here, usually in separate sessions on separate machines. Write every page so that someone with no memory of earlier conversations can pick it up and act on it.

The AGENTS.md and CLAUDE.md at the repo root send assistants here. Keep them working if you reorganize.

Start of every session

1. Read README.md. It's the index of every page.
2. Look at the last ~15 entries of log.md to see what changed recently: grep "^## \[" docs/log.md | tail -15
3. Read the pages that relate to your task. For planning work, also read plans/open-questions.md.

Don't work from memory of past conversations. The files are the source of truth, and anything that isn't written here isn't known yet, so write it down or ask. If the root ../README.md contradicts these docs, the docs win. Fix the README and mention the conflict.

Layout

Don't add top-level folders without a real need. If you do add one, put it in this table and in the README.

Where does it go?

• A fact we rely on that probably won't change soon → canonical/
• "We chose X over Y because…" → decisions/
• An idea, a draft design, or a list of next steps → plans/
• "We tried, measured, or read about X, and here's what we found" → research/

Pages graduate. Once the decision behind a plans/ sketch is accepted, the sketch becomes a canonical/ page. Move it rather than copying it, and fix the links.

Page format

File names are lowercase-kebab-case .md (hardware.md, pi-3b-plus-display-test.md). Decision files start with their date: decisions/2026-09-13-short-slug.md.

Every page except README.md, AGENTS.md, CLAUDE.md, and log.md starts with frontmatter:

---
title: Hardware
status: active          # draft | active | archived
updated: 2026-09-13     # date of the last meaningful edit
summary: One sentence. This is what goes in the index.
---

Decision pages use a different set of statuses and add the date and who decided:

---
title: Short statement of the decision
status: accepted        # proposed | accepted | rejected | superseded
date: 2026-09-13        # when it was decided (or proposed)
updated: 2026-09-13
decided_by: Ian, Kel
superseded_by:          # relative link to the newer decision, if any
summary: One sentence.
---

After the frontmatter comes a # Title heading and then the content. If there are related pages, end with a ## Related list of links.

Use relative markdown links like [Hardware](../canonical/hardware.md) so they work on GitHub. Don't use [[wikilinks]] or full URLs for pages in this repo.

Writing rules

1. Update before you create. Search first (grep -ri "keyword" docs/). Each topic lives on one page, because duplicates drift apart.
2. Keep pages short and skimmable. Bullets and tables work better than essays. If a page goes past ~300 lines, split it.
3. Keep facts and guesses apart. Mark anything unconfirmed (unverified) or move it to open questions. Don't present an assumption as a fact.
4. Record evidence. A test result needs the date, the hardware (e.g. "Pi 3B+, 1 GB, Raspberry Pi OS 64-bit"), what you measured, and the numbers.
5. Use absolute dates only. Write 2026-09-13, not "yesterday" or "next week".
6. Say who. If a decision or requirement came from Ian or Kel, name them.
7. Don't erase history. To change a decision, write a new decision that supersedes the old one. Archive pages you retire instead of deleting them.
8. Keep the root README honest. If a change touches the pitch, constraints, or technology direction, update ../README.md in the same change.
9. No secrets. No passwords, API keys, Wi-Fi credentials, or home network details.
10. No manual content. Never commit PDFs, rendered pages, or long passages from manuals. A short quote that explains a problem is fine.

Bookkeeping (every change)

• Index. If you created, renamed, moved, or archived a page, update its row in README.md (page, summary, status, updated). If you changed a page's summary or status, update its row too.

• Log. Append one entry to the bottom of log.md:

  ## [2026-09-13] update | Hardware
  Added Kel's Pi model. Requested by Kel.
  

  The types are create, update, decision, move, archive, and lint. Write one entry per logical change, not one per file, and never rewrite old entries.

• Date. Bump the page's updated: date.

Common tasks

Add something new (an idea, a fact, a test result)

1. Look for a page that already covers it. If there is one, update it.
2. Otherwise, create a page in the right folder, with frontmatter.
3. Link to it from at least one related page so it isn't orphaned.
4. Update the index and the log.

Record a decision

1. Create decisions/YYYY-MM-DD-slug.md from the template below. Use status proposed if Ian or Kel still has to sign off, and accepted once one of them agrees.
2. Update the pages it affects: canonical pages, the roadmap, and the root README if needed.
3. Take the matching item out of plans/open-questions.md, or point it at the decision.
4. If it replaces an older decision, set the old one to superseded and fill in its superseded_by.
5. Update the index and the log (type decision).

Answer a question from the docs

Read the index, open the relevant pages, and answer with links to the pages you used. If the docs don't cover it, say so rather than filling the gap from memory. If your answer pulled several pages together into something worth keeping, offer to save it as a page.

Tidy up (lint)

Do this when asked, or whenever you run into problems during other work. Look for:

• Pages missing from the index, and index rows that point to missing files
• Broken relative links
• Pages that contradict each other (the newer decision wins, so fix the older page)
• Open questions that a decision has already answered
• plans/ pages that are ready to graduate to canonical/, and pages that should be archived
• (unverified) claims that have since been tested

Fix whatever is clearly wrong, and list anything that needs a person to decide. Log it as lint.

Archive a page

Move the page into archive/ under the same file name and set status: archived. Under the title, add a line saying what replaced it and when. Then fix any links that pointed to it and update the index and the log.

Templates

Page

---
title:
status: draft
updated: YYYY-MM-DD
summary:
---

# Title

Content.

## Related
- [Page](../folder/page.md)

Decision

---
title:
status: proposed
date: YYYY-MM-DD
updated: YYYY-MM-DD
decided_by:
superseded_by:
summary:
---

# Title

## Context
The problem or question that forced a choice.

## Decision
What we're doing, in a sentence or two.

## Options considered
- **Option A**: pros and cons
- **Option B**: pros and cons

## Consequences
What this makes easier, what it makes harder, and what it rules out. What would make us revisit it.

## Related
- [Page](../folder/page.md)

Git

• Docs changes are ordinary commits (e.g. docs: record display stack decision). When practical, commit docs and code separately.
• Follow the instructions of the person you're working with about committing and pushing. Don't push unless they ask.
• If log.md has a merge conflict, keep the entries from both sides, in date order.