# Goldfish

> A voice recorder with no radio. Each voice sets how much of its words are kept, the record forgets on a schedule, and the device answers with light, never sound. An open kit (v01: a 182 × 85 × 37 mm printed pebble round a Radxa ZERO 3E, about 266 g) and a device-independent draft standard, the Resolution Protocol.

The landing page (https://npc.here.now/demo-goldfish/) explains what Goldfish is for. The workbench (https://npc.here.now/demo-goldfish/workbench/) shows the specification, the 3D model with every wire pad to pad, the print files, and the firmware running in the browser. Everything below is the repository's own text, served raw. Model-written text in the product is labelled machine-generated. Licences: code Apache-2.0, hardware CERN-OHL-P-2.0, docs CC BY 4.0.

## Pick this up
- [README.md](https://npc.here.now/demo-goldfish/files/README.md): Repository overview
- [AGENTS.md](https://npc.here.now/demo-goldfish/files/AGENTS.md): Contributing: the pipeline, the checks, the rules
- [BUILD-LOG.md](https://npc.here.now/demo-goldfish/files/BUILD-LOG.md): Build log: history and current state, "Start here" at the top

## Build the kit
- [v01/README.md](https://npc.here.now/demo-goldfish/files/v01/README.md): v01 kit overview
- [v01/assembly.md](https://npc.here.now/demo-goldfish/files/v01/assembly.md): Assembly: who it is for, tools, LiPo safety, steps, bring-up checks
- [v01/wiring.md](https://npc.here.now/demo-goldfish/files/v01/wiring.md): Wiring, pad level
- [v01/bom.csv](https://npc.here.now/demo-goldfish/files/v01/bom.csv): Bill of materials (every part, buy links)
- [v01/profile/goldfish.profile.json](https://npc.here.now/demo-goldfish/files/v01/profile/goldfish.profile.json): Goldfish profile (the device's settings, as an RP profile)
- [v01/note-format.md](https://npc.here.now/demo-goldfish/files/v01/note-format.md): Note format: the Markdown a phone receives, for people and language models

## Resolution Protocol
- [protocol/README.md](https://npc.here.now/demo-goldfish/files/protocol/README.md): Protocol overview and quick start
- [protocol/SPEC.md](https://npc.here.now/demo-goldfish/files/protocol/SPEC.md): Specification (RP 0.2 draft)
- [protocol/research/prior-art.md](https://npc.here.now/demo-goldfish/files/protocol/research/prior-art.md): Prior art
- [protocol/js/resolution.js](https://npc.here.now/demo-goldfish/files/protocol/js/resolution.js): Reference implementation, JavaScript
- [protocol/js/conformance.js](https://npc.here.now/demo-goldfish/files/protocol/js/conformance.js): Conformance runner, JavaScript
- [protocol/locales/en.json](https://npc.here.now/demo-goldfish/files/protocol/locales/en.json): English grammar
- [protocol/locales/es.json](https://npc.here.now/demo-goldfish/files/protocol/locales/es.json): Spanish grammar (draft)
- [protocol/vectors/sessions.json](https://npc.here.now/demo-goldfish/files/protocol/vectors/sessions.json): Session vectors
- [protocol/vectors/phrases.en.json](https://npc.here.now/demo-goldfish/files/protocol/vectors/phrases.en.json): Phrase vectors, English
- [protocol/vectors/retention.json](https://npc.here.now/demo-goldfish/files/protocol/vectors/retention.json): Retention vectors
- [protocol/vectors/profiles.json](https://npc.here.now/demo-goldfish/files/protocol/vectors/profiles.json): Profile vectors
- [protocol/schemas/profile.schema.json](https://npc.here.now/demo-goldfish/files/protocol/schemas/profile.schema.json): Profile schema
- [protocol/schemas/locale.schema.json](https://npc.here.now/demo-goldfish/files/protocol/schemas/locale.schema.json): Locale schema
- [protocol/schemas/event.schema.json](https://npc.here.now/demo-goldfish/files/protocol/schemas/event.schema.json): Event schema

## Decisions and plans
- [ROADMAP.md](https://npc.here.now/demo-goldfish/files/ROADMAP.md): Roadmap
- [BACKLOG.md](https://npc.here.now/demo-goldfish/files/BACKLOG.md): Backlog
- [03-architecture/code.md](https://npc.here.now/demo-goldfish/files/03-architecture/code.md): Code architecture
- [03-architecture/decisions/0001-no-radio.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0001-no-radio.md): ADR-0001: No wireless radio in v1
- [03-architecture/decisions/0002-retention-by-crypto-shredding.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0002-retention-by-crypto-shredding.md): ADR-0002: Retention enforced by destroying per-session keys
- [03-architecture/decisions/0003-voice-in-plain-english.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0003-voice-in-plain-english.md): ADR-0003: People set resolution by talking to the device
- [03-architecture/decisions/0004-physical-access-only.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0004-physical-access-only.md): ADR-0004: Memory is reached only by physically handling the device
- [03-architecture/decisions/0005-forgetting-by-tiers.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0005-forgetting-by-tiers.md): ADR-0005: Forgetting by tiers — distil every rung up front, then destroy keys on schedule
- [03-architecture/decisions/0006-light-language.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0006-light-language.md): ADR-0006: The device answers with light, never with sound
- [03-architecture/decisions/0007-passive-nfc-handoff.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0007-passive-nfc-handoff.md): ADR-0007: Hand-off to a phone through a passive NFC tag
- [03-architecture/decisions/0008-per-participant-resolution.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0008-per-participant-resolution.md): ADR-0008: Resolution per participant, not per device
- [03-architecture/decisions/0009-flank-lights.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0009-flank-lights.md): ADR-0009: A light ring at the seam, one light in the eye
- [03-architecture/decisions/0010-each-voice-owns-its-record.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0010-each-voice-owns-its-record.md): ADR-0010: Each voice gains an identity and owns its record
- [03-architecture/decisions/0011-protocol-and-profile.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0011-protocol-and-profile.md): ADR-0011: Resolution Protocol and the Goldfish profile
- [03-architecture/decisions/0012-rp-0-2.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0012-rp-0-2.md): ADR-0012: Resolution Protocol 0.2 — provisional raises, a smaller core, adoption hooks
- [03-architecture/decisions/0013-eye-button-and-kit-build.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0013-eye-button-and-kit-build.md): ADR-0013: The eye is a button; the room-off glow; a kit with no surface-mount soldering
- [03-architecture/decisions/0014-bigger-cell-and-continuous-power.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0014-bigger-cell-and-continuous-power.md): ADR-0014: One bigger cell, a bigger pebble, and continuous running on a phone charger
- [03-architecture/decisions/0015-usability-and-build-round.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0015-usability-and-build-round.md): ADR-0015: Usability and build round: safe eye presses, reachable switches, buttonless phone transfer, a buildable shell
- [03-architecture/decisions/0016-flared-post-roots.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0016-flared-post-roots.md): ADR-0016: Flared roots on the board posts
- [03-architecture/decisions/0017-print-practice-and-fasteners.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0017-print-practice-and-fasteners.md): ADR-0017: Print practice from the community, and the fasteners in the model
- [03-architecture/decisions/0018-every-board-screwed-down.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0018-every-board-screwed-down.md): ADR-0018: Every board screwed down, for a prototype that is rebuilt often
- [03-architecture/decisions/0019-firmware-in-the-site.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0019-firmware-in-the-site.md): ADR-0019: The site's meeting runs the real firmware, and a flow test replays it
- [03-architecture/decisions/0020-chassis-and-lid.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0020-chassis-and-lid.md): ADR-0020: A chassis and a lid: every board in the bottom shell, one plug to the top
- [03-architecture/decisions/0021-pad-level-wiring.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0021-pad-level-wiring.md): ADR-0021: Wiring at pad level: every wire from a named pad to a named pad
- [03-architecture/decisions/0022-landing-page.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0022-landing-page.md): ADR-0022: A landing page at the site root; the workbench moves to /workbench/
- [03-architecture/decisions/0023-mods.md](https://npc.here.now/demo-goldfish/files/03-architecture/decisions/0023-mods.md): ADR-0023: Mods: add-on packs that can only lower

## Source code
- [v01/firmware/goldfish/__init__.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/__init__.py): Goldfish v01 — the device side of the Resolution Protocol
- [v01/firmware/goldfish/audio.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/audio.py): Audio in: the two SPH0645 microphones on I2S3 (wiring.md §2), or a WAV file, as frames at one rate
- [v01/firmware/goldfish/daemon.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/daemon.py): The main loop: eye → device → display → ring and motor; meeting end → note → NFC tag; power
- [v01/firmware/goldfish/device.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/device.py): Goldfish as one profile of the Resolution Protocol (SPEC §8, §10.3)
- [v01/firmware/goldfish/display.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/display.py): What the lights show (ADR-0009). Shared by firmware, the site and the phone view
- [v01/firmware/goldfish/eye.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/eye.py): The eye switch (SW3, DTS-61K on pin 16, pull-up, closes to GND): edges in, gestures out
- [v01/firmware/goldfish/handoff.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/handoff.py): Hand-off to a phone over a passive NFC tag (ADR-0007)
- [v01/firmware/goldfish/haptic.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/haptic.py): The ERM disc (M1) on pin 18 through a PN2222A (wiring.md §5): plays display.HAPTIC patterns
- [v01/firmware/goldfish/hw.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/hw.py): The hardware boundary: a clock, GPIO in and out, SPI and I2C. Nothing else in the firmware touches the board
- [v01/firmware/goldfish/hw_linux.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/hw_linux.py): The Radxa ZERO 3E under Radxa's Debian, through python-periphery
- [v01/firmware/goldfish/keys.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/keys.py): Forward-secure key chains (v01/research/software-stack.md, "Key management")
- [v01/firmware/goldfish/meeting.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/meeting.py): The firmware in a scripted meeting, on a sim board (ADR-0019)
- [v01/firmware/goldfish/power.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/power.py): Clean shutdown (backlog B-44): when the power slide goes off, finish the meeting before the power goes
- [v01/firmware/goldfish/ring.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/ring.py): Display frames (display.py) → the SPI bitstream for the NeoPixel chain (wiring.md §3)
- [v01/firmware/goldfish/st25dv.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/st25dv.py): ST25DV64KC dynamic NFC tag over I2C (SparkFun Qwiic Dynamic NFC/RFID Tag)
- [v01/firmware/goldfish/store.py](https://npc.here.now/demo-goldfish/files/v01/firmware/goldfish/store.py): Sealed, tiered memory (ADR-0005 + key chains in keys.py)
- [v01/firmware/js/goldfish.js](https://npc.here.now/demo-goldfish/files/v01/firmware/js/goldfish.js): goldfish.js
- [protocol/python/resolution_protocol/__init__.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/__init__.py): Resolution Protocol — reference implementation (Python). Normative text: protocol/SPEC.md
- [protocol/python/resolution_protocol/conformance.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/conformance.py): Run the protocol's conformance vectors against this implementation (SPEC §12)
- [protocol/python/resolution_protocol/exchange.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/exchange.py): Exchange between recorders, and standing preferences (SPEC §11)
- [protocol/python/resolution_protocol/grammar.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/grammar.py): Locale grammars (SPEC §7): spoken phrases → language-neutral intents
- [protocol/python/resolution_protocol/levels.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/levels.py): The six levels (SPEC §3). Each keeps everything the levels below it keep. Closed: no extensions
- [protocol/python/resolution_protocol/profile.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/profile.py): Profiles (SPEC §8): one recorder's expression of the protocol — parameters and localisation
- [protocol/python/resolution_protocol/retention.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/retention.py): Retention (SPEC §5): the highest level content may still be read at a given age
- [protocol/python/resolution_protocol/session.py](https://npc.here.now/demo-goldfish/files/protocol/python/resolution_protocol/session.py): Sessions, voices and records (SPEC §4–6)
- [v01/cad/board_pads.py](https://npc.here.now/demo-goldfish/files/v01/cad/board_pads.py): Where each board sits and turns, and where its pads are: one frame for the wire router, the checks and the site
- [v01/cad/buildability.py](https://npc.here.now/demo-goldfish/files/v01/cad/buildability.py): Can a builder who orders every part actually build the kit? Walks the build the way the assembly guide does
- [v01/cad/enclosure.py](https://npc.here.now/demo-goldfish/files/v01/cad/enclosure.py): Goldfish v01 — printable enclosure from the verified layout
- [v01/cad/layout.py](https://npc.here.now/demo-goldfish/files/v01/cad/layout.py): Goldfish v01 — parametric layout and fit check
- [v01/cad/make_viewer.py](https://npc.here.now/demo-goldfish/files/v01/cad/make_viewer.py): Bundle out/*.stl + out/parts.json into ../viewer.html (opens from disk, no server)
- [v01/cad/make_web.py](https://npc.here.now/demo-goldfish/files/v01/cad/make_web.py): After pebble_enclosure.py: simplified meshes for the website (out_pebble/web/) and print.json
- [v01/cad/pebble.py](https://npc.here.now/demo-goldfish/files/v01/cad/pebble.py): Pebble body: a loft of superellipse cross-sections
- [v01/cad/pebble_enclosure.py](https://npc.here.now/demo-goldfish/files/v01/cad/pebble_enclosure.py): Goldfish v01c — printable pebble enclosure, designed for drops and hands
- [v01/cad/pebble_layout.py](https://npc.here.now/demo-goldfish/files/v01/cad/pebble_layout.py): Goldfish v01b — pebble layout by greedy packing against the analytic cavity
- [v01/cad/review_geometry.py](https://npc.here.now/demo-goldfish/files/v01/cad/review_geometry.py): Geometric review of the v01c pebble: openings, light windows, strip path, ports, controls, structure
- [v01/cad/section.py](https://npc.here.now/demo-goldfish/files/v01/cad/section.py): Cut the printed meshes with a plane and draw the section, with the parts' layout boxes it crosses
- [v01/cad/stages.py](https://npc.here.now/demo-goldfish/files/v01/cad/stages.py): Resume a long CAD build from the last section whose code and inputs haven't changed
- [v01/cad/stamps.py](https://npc.here.now/demo-goldfish/files/v01/cad/stamps.py): Input stamps for the generated CAD files, so a stale step shows up as a failed check, not as wrong numbers
- [v01/cad/wire_routes.py](https://npc.here.now/demo-goldfish/files/v01/cad/wire_routes.py): Route every wire of wiring.md through the free space of the closed pebble, and check that the case fits them
- [v01/cad/pebble_spec.json](https://npc.here.now/demo-goldfish/files/v01/cad/pebble_spec.json): pebble_spec.json
- [v01/sim/power_sim.py](https://npc.here.now/demo-goldfish/files/v01/sim/power_sim.py): Electrical simulation of the v01 kit: power tree, battery discharge, rails, logic levels, I2C, drivers
- [v01/sim/design.json](https://npc.here.now/demo-goldfish/files/v01/sim/design.json): design.json
- [v01/build.py](https://npc.here.now/demo-goldfish/files/v01/build.py): Rebuild whatever is stale, in pipeline order, then validate
- [v01/validate.py](https://npc.here.now/demo-goldfish/files/v01/validate.py): Run every check for v01 and write validation.json (shown on the overview site)
- [site/build.py](https://npc.here.now/demo-goldfish/files/site/build.py): Build site/index.html — the Goldfish workbench (opens from disk) — and, with --web, the deploy folder site/web/:

## Optional
- [LICENSE](https://npc.here.now/demo-goldfish/files/LICENSE): Which licence covers what
- [LICENSES/Apache-2.0.txt](https://npc.here.now/demo-goldfish/files/LICENSES/Apache-2.0.txt): Apache 2.0 (code)
- [LICENSES/CERN-OHL-P-2.0.txt](https://npc.here.now/demo-goldfish/files/LICENSES/CERN-OHL-P-2.0.txt): CERN-OHL-P v2 (hardware design files)
- [LICENSES/CC-BY-4.0.txt](https://npc.here.now/demo-goldfish/files/LICENSES/CC-BY-4.0.txt): CC BY 4.0 (specification, docs, data)

## Downloads
- [Source zip](https://npc.here.now/demo-goldfish/files/goldfish-source.zip): everything in the repository except vendor models and generated meshes
- [Print files](https://npc.here.now/demo-goldfish/print/): the STL files and the print settings