scaffold: OpenScribe open-source self-hosted AI voice recorder

Bootstrap of the project (M0). Sets up the monorepo, design docs, hardware BOM,
the open API contract, component skeletons, licensing and CI, following the
Default Workflow SOP.

What changed:
- CLAUDE.md + docs/: copied the Default Workflow so sessions load the SOP.
- state/: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES filled in for OpenScribe.
  ARCHITECTURE captures the four-part design (firmware, server, app, case) and the
  three sync paths; DECISIONS records the hardware, AI-stack, storage, app and
  licensing choices; TODO lays out milestones M1-M9.
- hardware/BOM.md: two build options (compact XIAO ESP32-S3 Sense; dev ESP32-S3 +
  I2S mic + SD), wiring/pinout, indicative cost.
- api/openapi.yaml: the completely open API (device + server surfaces), including
  recording list/download/delete and exports (wav/ogg/txt/srt/vtt/md/json).
- firmware/: PlatformIO ESP32-S3 project, two board profiles, pin map, boot scaffold
  with module seams for M1-M4.
- server/: FastAPI skeleton mirroring the OpenAPI, config for self-hosted MinIO,
  faster-whisper and Ollama; stub routes browsable at /docs.
- app/, case/: Flutter app plan; parametric OpenSCAD enclosure.
- Licensing: GPL-3.0 (code), CERN-OHL-S-2.0 (hardware), CC-BY-SA-4.0 (case/docs),
  REUSE-style LICENSES/ with SPDX headers; LICENSING.md explains the split.
- CI: Forgejo Actions workflow builds firmware (both profiles) and lints/imports server.

Why:
- Everything self-hosted and openly licensed per the user's requirements: an open
  API, three sync paths (BLE control, WiFi transfer, independent WiFi upload on
  charge to generic cloud storage), and a full self-hosted transcription+summary stack.

Notes:
- No custom PCB in v1; off-the-shelf modules. Physical verification waits on parts.
- Component code is stubs at M0; features land milestone by milestone, each as its
  own branch/PR per the workflow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/documentation-policy.md

@@ -0,0 +1,54 @@
+# Documentation policy
+
+Two separate ideas, both about making the repo the single source of truth so that no
+session ever depends on another session's chat history.
+
+## A. State lives in committed markdown, not in the chat
+
+Do not use chat history, context, or cache as memory. They cost tokens to carry and
+vanish between sessions. Instead, everything a future session needs is written to the
+`state/` directory and committed:
+
+| File | Holds |
+|------|-------|
+| `PROJECT.md` | Objectives, scope, description, audience. The anchor. |
+| `ARCHITECTURE.md` | How the system is built and why it is built that way. |
+| `DECISIONS.md` | A dated log of decisions and their rationale. Append, never rewrite history. |
+| `TODO.md` | Done / in progress / pending. The current state of play. |
+| `NOTES.md` | Working notes, gotchas, environment quirks, dead ends to avoid. |
+
+Update these as part of the work, not as an afterthought. A change to how the system
+works is not finished until `ARCHITECTURE.md` or `DECISIONS.md` reflects it.
+
+Templates for all of these are in `templates/`.
+
+## B. Documentation is written in a separate session from the code
+
+The user facing documentation (README, guides, API docs, changelog) is **not** written
+in the same session that writes the code. This is deliberate:
+
+- It forces the building session to leave a complete trail. If the code cannot be
+  documented later from git history and comments alone, the trail was not good enough.
+- It keeps each session cheap and focused. A building session spends its budget
+  building; a documentation session spends its budget writing docs.
+- It gives the docs a cold, independent reader who documents what the code actually
+  says, not what the author remembers intending.
+
+### What the building session must leave behind
+
+So the later documentation session can work with no chat history:
+
+1. **Commit messages with full notes** - what changed, why, and any trade-offs. See
+   [Workflow](workflow.md).
+2. **A complete PR description** - feature, tools used, what was achieved, how it works.
+3. **Code comments that explain intent** - not what a line does (the code shows that)
+   but why it exists, what it assumes, and what would break it. Comment for a stranger
+   who was not in the room.
+4. **Current `state/` files** - especially `ARCHITECTURE.md` and `DECISIONS.md`.
+
+### What the documentation session does
+
+Starts cold. Reads `git log`, the PRs, the code and its comments, and the `state/`
+files. Writes the documentation from those alone. If something cannot be understood
+from the repo, that is a gap to flag, not a reason to guess or to reach for lost chat
+context.

docs/project-setup.md

@@ -0,0 +1,63 @@
+# Project setup
+
+How to start a new project on the Default Workflow. Do this once, at the beginning of
+a project, before any feature work.
+
+## 1. Create the repository
+
+- Create an empty repo on the forge (git.discworld.casa or wherever the project lives).
+- Clone it, or `git init` locally and add the remote.
+- The trunk branch is `main` unless the forge defaults to `master`; either is fine, be
+  consistent and refer to it as "the trunk" in docs.
+
+## 2. Copy the workflow files in
+
+From this Default-Workflow repo, copy into the new project root:
+
+- `CLAUDE.md` - so every session loads the workflow automatically.
+- `docs/` - the detailed workflow docs (or link to them if you prefer one source of
+  truth; copying keeps the project self contained and offline readable).
+- `templates/*` into `state/` (see next step).
+
+## 3. Create the state directory
+
+The `state/` directory is the project's memory. It replaces chat history. Copy the
+templates and fill in the project specifics:
+
+```
+state/
+  PROJECT.md      - objectives, scope, description, who it is for
+  ARCHITECTURE.md - how the system is built and why
+  DECISIONS.md    - dated log of decisions and their rationale
+  TODO.md         - what is done, in progress, and pending
+  NOTES.md        - working notes, gotchas, environment quirks
+```
+
+Fill in `PROJECT.md` first. It anchors every later session. A session that reads only
+`PROJECT.md`, `TODO.md` and `DECISIONS.md` should understand what the project is and
+what to do next.
+
+## 4. Add a .gitignore
+
+Ignore build artefacts, dependencies, secrets and local scratch. Never commit tokens
+or credentials.
+
+## 5. First commit
+
+Commit the scaffold to the trunk directly (this is bootstrap, not a feature):
+
+```
+git add .
+git commit
+```
+
+Write a full commit message describing what the scaffold contains and why. From here
+on, all work follows the [Workflow](workflow.md): a branch per feature.
+
+## Checklist
+
+- [ ] Repo created and remote set
+- [ ] `CLAUDE.md` and `docs/` present in project root
+- [ ] `state/` created from templates, `PROJECT.md` filled in
+- [ ] `.gitignore` in place, no secrets tracked
+- [ ] Scaffold committed to the trunk

docs/user-expectations.md

@@ -0,0 +1,46 @@
+# User expectations
+
+How the user expects a Claude Code session to behave under this workflow. Read this
+once per session; it rarely changes.
+
+## Work autonomously
+
+Do not stop to ask which task to pick up next, or for confirmation before routine work.
+Default sensibly and keep shipping. Read `state/TODO.md`, choose the next sensible
+item, do it. Only ask when a decision is genuinely the user's to make and cannot be
+resolved from the repo or sensible defaults.
+
+## Cost before speed
+
+Staying within usage limits is more important than finishing fast or gold plating.
+When in doubt, take the cheaper path. See [Cost and tokens](cost-and-tokens.md).
+
+## Leave a clean trail
+
+Every feature ends as: a merged branch, full commit notes, a complete PR, current
+`state/` files, and code commented well enough to document later. The user should be
+able to open the repo weeks later, with no memory of the session, and understand what
+happened and why from the repo alone.
+
+## Report honestly
+
+If tests fail, say so with the output. If a step was skipped, say that. If something is
+done and verified, say so plainly without hedging. Do not claim more than was done.
+
+## Writing style
+
+- No em dashes in prose. Use commas, full stops, or restructure.
+- British spelling in prose and copy. Preserve code identifiers as written.
+- Plain, direct language. Say what happened.
+
+## Confirm before the hard to reverse
+
+Routine coding is autonomous. But confirm first for actions that are hard to undo or
+that reach outside the repo: force pushes, history rewrites, deleting things you did
+not create, deploying, or sending data to external services. Approval for one such
+action does not carry to the next.
+
+## The building session stops at merge
+
+Do not write the user facing documentation in the building session. That is a separate
+session's job. See [Documentation policy](documentation-policy.md).

docs/workflow.md

@@ -0,0 +1,76 @@
+# Workflow
+
+The branch, commit, PR and merge process for every feature. A "feature" is any unit of
+change: a new capability, a fix, a refactor.
+
+## 1. Branch per feature
+
+Never build directly on the trunk. Start each feature from an up to date trunk:
+
+```
+git checkout main
+git pull
+git checkout -b feature/<short-kebab-description>
+```
+
+Use a clear prefix: `feature/`, `fix/`, `refactor/`, `docs/`.
+
+## 2. Commit with full notes
+
+Commit in logical steps, not one giant dump at the end. Every commit message carries
+the full record of what changed and why, because the commit history is the primary
+source a later documentation session reads.
+
+Message shape:
+
+```
+<type>: <concise summary in the imperative>
+
+What changed:
+- <file or area>: <what and why>
+- ...
+
+Why:
+- <the reasoning, constraints, or decision behind the change>
+
+Notes:
+- <anything a cold session should know: trade-offs, follow-ups, gotchas>
+```
+
+Do not write "written by Claude" in code or messages. If the project convention
+requires an authorship tag (for example `ai:claude`), follow that project's rule.
+
+## 3. Keep state files current
+
+As you work, update `state/TODO.md` and `state/DECISIONS.md`. Decisions go in the log
+with a date and rationale. This is what lets the next session skip the chat history.
+
+## 4. Open a PR when the feature is complete
+
+When the feature is done and self consistent, push the branch and open a PR. The PR
+description is the human and machine readable summary of the feature. Use the template
+in `templates/PR_TEMPLATE.md`. It must state:
+
+- **Feature** - what was built, in plain terms.
+- **What was achieved** - the outcome, and how to verify it.
+- **Tools used** - languages, libraries, commands, services involved.
+- **How it works** - enough for a documentation session to start from the PR alone.
+- **Follow ups** - anything deferred.
+
+## 5. Merge into the trunk
+
+Merge the PR into the trunk once it is complete. Prefer a merge that preserves the
+commit history (the notes in each commit are valuable). Delete the feature branch after
+merge.
+
+## 6. Do not document in this session
+
+Writing the user facing documentation is a separate job, done in a separate session,
+against the merged history. See [Documentation policy](documentation-policy.md). Your
+job in the building session ends at a merged, well commented, well described feature.
+
+## Summary
+
+```
+branch  ->  commit (full notes)  ->  update state/  ->  PR (feature, tools, outcome)  ->  merge  ->  stop
+```