Skip to content
Porthole organization iconPorthole

The second brain

What two postmarketOS ports taught us, written so an LLM can use it.

The corpus is plain markdown with YAML frontmatter. No database, no index required to read it, no harness assumed — grep, cat, an agent’s file reader, and a human all work equally well. porthole brain only makes it findable.

Start here

Section: Start here
you are read
an agent starting a session workflow/agent-protocol.md, then laws/
starting a new device playbooks/10-first-boot.md and your profile’s checklist.md
about to touch the device playbooks/00-device-protocol.md
about to report a result laws/every-test-needs-a-positive-control.md
stuck on a subsystem playbooks/, then porthole brain <keyword>

If you read one directory, read laws/. Ten notes, none of them about phones specifically, and they are what separate a week of progress from a week of confidently testing nothing.

Layout

Section: Layout
  • laws/ — cross-device methodology. The most portable thing here.
  • findings/ — a question this port has CLOSED, and the theories it kills. The largest section, and the one to search before forming a theory: a trap says “do not do X”, a finding says “X is already answered, and here is what is now dead”.
  • traps/ — specific failure modes, each citing the evidence that proved it.
  • playbooks/ — ordered bring-up recipes: what to do, in what order, and what counts as done.
  • workflow/ — how to work: device etiquette, evidence discipline, handoffs, commit conventions.
  • devices/ — per-device records, linking out to the full evidence archive.
  • memory/ — long-lived agent memory.
  • INDEX.md — generated by porthole brain reindex.

Frontmatter

Section: Frontmatter
---
id: usb-gadget-lies-as-fastboot          # kebab-case, matches the filename
title: lsusb labels a running gadget as "fastboot"
scope: generic                            # generic | soc:<soc> | device:<codename>
subsystem: boot
severity: law | finding | trap | technique | fact
confidence: proven | probable | suspected
evidence: <where the proof lives>
first-learned: 2026-07-25
---

scope is the load-bearing field. It is what lets someone on a Snapdragon 845 device read the generic laws and skip the msm8998 register trivia:

Terminal window
porthole brain search --scope soc:sdm845        # generic + sdm845, nothing else
porthole brain search --severity law            # just the methodology
porthole brain watchdog --json           # for a machine

A scope filter always includes generic. Hiding the laws from someone who filtered to their device would be the opposite of what they asked for.

Contributing

Section: Contributing

A note earns its place if it would have saved someone a session.

  • One idea per note. If the title needs an “and”, it is two notes.
  • Cite the evidence. A trap without a source is folklore, and folklore is what this corpus exists to replace.
  • Say what the symptom looks like, not just what the cause is. People search by symptom — they do not yet know the cause; that is why they are searching.
  • Prefer the generic scope, honestly. If it only ever applied to one device, scope it there. Over-claiming portability is worse than scoping narrowly.
  • Link liberally with note-id. A trap that is an instance of a law should say so, and the law should list its instances.
  • Run porthole brain reindex after adding a note.

Dates are absolute. “Last week” is unreadable in a month, and an agent reading this has no idea when you wrote it.