brainiphy

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

This repo *is* the source for a Claude Code Skill (`SKILL.md`) plus the Python package it depends on (`src/brainiphy_cli/`). It is symlinked at `~/.claude/skills/brainiphy` — editing files here takes effect immediately for any Claude session that invokes the skill, no reinstall needed for the skill file itself (the Python package does need an editable install, see below).

The skill's job: turn "install graphify, feed it data, wire it to Claude" into a repeatable playbook for bootstrapping a queryable knowledge-graph "brain" for a business/client, reused across client projects. `SKILL.md` is the playbook an agent follows; `brainiphy_cli` is the tool it runs.

Read `SKILL.md` first — it is the primary spec for both the CLI's behavior and the order of operations an agent should follow. This CLAUDE.md covers what SKILL.md doesn't: install/dev commands and code architecture.

The prose docs are split by audience, and a change usually belongs in exactly one of them: `README.md` is for someone deciding whether to use brainiphy and then using it — plain language, no flag tables, built around the figures in `docs/`; `docs/reference.md` is every command and flag, the on-disk layout and the connector contract; `CONTRIBUTING.md` is working on the repo itself. Don't grow the README back into a reference — that is what it was, and the flags are now one link away. The figures it embeds are generated by `scripts/gen-docs-images.py` from real `brain` output; edit that script, never the SVGs.

## Install / dev commands

```
/usr/local/opt/python@3.11/bin/python3.11 -m pip install --user -e ~/.claude/skills/brainiphy
```

Editable install — required once so the `brain` binary exists on PATH; after that, edits to `src/brainiphy_cli/*.py` take effect immediately (no reinstall). Re-run it after touching `dependencies` in `pyproject.toml` (currently `pyyaml`, `rich`) — an editable install does not pick up new deps on its own, and a missing `rich` breaks every command, since `ui.py` imports it at module level. Confirm the interpreter actually used with `head -1 $(which graphify)` — this machine has multiple Python 3 installs and `brain`/`graphify` must both resolve to the same one, or `brain sync`'s `find_graphify()` / `_find_exe()` PATH lookups can pick the wrong one.

Two test layers, both run by CI (`.github/workflows/ci.yml`) on macOS and Linux across the supported Python versions:

```
python -m unittest discover -s tests        # unit suite — no graphify, no network, no TTY
./scripts/smoke.sh                          # end-to-end against the real `brain` binary
```

The unit suite is plain `unittest` on purpose — the house rule is no new tooling without a reason, and this adds no dependency to install before it can run. It targets the decisions that fail *silently* rather than loudly: `resolve_backend()`, which graphify command `build_graph()` picks and with which flags, `is_due()`, the slug/escaping contract in `frontmatter.py`, what `steps.inspect()` reads off disk, and the retry/`NoScope` behavior of `httpclient.py`. `tests/support.py` holds the temp-project fixture and `quiet()`, which swallows the `ui` output every operation prints.

There is no lint/format config — match existing style (plain argparse, dataclasses, `from __future__ import annotations`) rather than introducing a new tool.

To exercise a change manually, run the CLI against a scratch directory:
```
brain init /tmp/some-test-project
brain new-connector /tmp/some-test-project demo --interval-minutes 5
brain new-connector /tmp/some-test-project docs --mirror /tmp/some-source-folder
brain presets
brain new-connector /tmp/some-test-project crm --preset gohighlevel --var LOCATION_ID=abc123
brain new-connector /tmp/some-test-project api --api https://api.example.com
brain sync /tmp/some-test-project --dry-run
brain guide /tmp/some-test-project
brain status /tmp/some-test-project
```

A generated API/preset connector can be exercised without a full sync: `"$(head -1 "$(which brain)" | cut -c3-)"
<project>/connectors/<name>/sync.py --out /tmp/probe --probe` hits the real API and reports which objects the
credential can read, writing nothing. Name the interpreter like that rather than running the script directly —
its shebang is `env python3`, which on this machine is *not* the install `brainiphy_cli` lives under, so the
script dies on its own import. `--only <collector>` narrows it further. That is the fastest way to check a change to `httpclient.py`
or `collect.py` against a live API.

The app (`brain` / `brain new`) can't be exercised that way — it refuses without a TTY, and piping answers into it through
`script -q /dev/null` doesn't work either (the pty eats stdin). Drive `app.run()` from a Python snippet that replaces
`keys.supported`, `picker.is_interactive`, `keys.read_key` and the `prompt.*` functions with scripted
answers instead; that covers the whole flow including the real subprocess calls.

Driving it means feeding keypresses. Use `app.run()` with
`keys.supported`, `picker.is_interactive` and `keys.read_key` replaced, feeding an iterator of key names, and
stub `ui.clear` so the screens stay in the scrollback:
```python
from brainiphy_cli import keys, picker, app, ui
keys.supported = lambda: True; picker.is_interactive = lambda: True; ui.clear = lambda: None
seq = iter(["enter", "q"])           # run the current step, then quit
keys.read_key = lambda: next(seq)
app.run("/path/to/brain")
```
Count the keypresses carefully: `_pause()` after a framed action reads one, and so does `_prepare()` on a folder
that was not scaffolded yet — an off-by-one shows up as a screen redrawing instead of advancing, which looks like
a bug in the code under test and is not. Replace `prompt.ask`/`confirm`/`choose`/`ask_path` with scripted answers
for anything that asks questions (`actions.py`, the picker's `/` path).

## Architecture

**`src/brainiphy_cli/cli.py`** — argparse entry point (`brain` console script). Each subcommand (`menu`, `new`, `guide`, `init`, `presets`, `new-connector`, `sync`, `connect-claude`, `schedule`, `secret set/get`, `status`) is a standalone `cmd_*` function; there's no shared command base class or plugin system to look for. Bare `brain` (no subcommand) opens the menu, which is why the subparsers are `required=False`.

A subparser marked `set_defaults(framed=True)` has its output drawn inside the app box by `main()`. Three groups are deliberately unmarked: anything that prompts mid-run (`new`, `init` without a path, `secret set`) — a framed block shows nothing until it ends, so a prompt inside one is invisible; `sync`, which streams for minutes; and `secret get`, which must stay bare on stdout to be pipeable. Framing is additionally gated on `ui.out.is_terminal`, so `brain status > file` still writes plain text rather than box-drawing characters. Keep it as argparse plumbing only — the actual work belongs in `project.py`/`sync.py`/`app.py`/`actions.py`, so the guided flow and the individual commands can't drift apart. All user-facing output is in English (it was Spanish until the repo was translated — don't reintroduce Spanish strings).

**`src/brainiphy_cli/steps.py`** — the machine-readable version of the playbook `SKILL.md` describes in prose: seven ordered `Step`s, and `inspect(project)` which resolves each one against what's on disk. `brain guide` renders it, `brain status` uses it for its next-step line, and the app walks it. **If the process changes, it changes here and in SKILL.md together** — this is the copy a user actually sees. Notes:
- `render()` and `render_status()` live here rather than in cli.py so `app.py` shows the same screens the commands print, without cli.py and app.py importing each other.
- A step's `done` covers both `DONE` and `SKIP` (not applicable, e.g. "implement the connectors" on a brain that only mirrors folders) — `SKIP` renders as a dash, and must not block the next-step pointer.
- Step 4 counts a connector as unfinished for two different reasons, and says which: a `raise NotImplementedError` left by a stub template, or a `CONST = "REPLACE_ME"` in a preset whose account details were never supplied. Both are detected as source text, never by importing the script — a half-written connector may not import at all. The placeholder half is read through `project.unfilled_placeholders()`, not a pattern of its own: there were two regexes and they disagreed about a digit in the suffix, so `brain new-connector` called a connector ready while `brain status` refused to tick step 4 for it.
- Detection is read-only and cheap; it runs on every `brain status`. Don't add subprocess calls to it.

**`src/brainiphy_cli/brains.py`** — the list of brains this machine knows about, at `~/.config/brainiphy/brains.yaml` (or under `$BRAINIPHY_HOME`, which is what keeps tests and `scripts/smoke.sh` off the real one). It exists because the tool could not answer the first question anyone with more than one client asks: *which brains do I have, and which has gone stale?* Three rules:
- It stores **paths and nothing else**. Every fact on screen — steps done, graph size, sources ready, last sync — is read from the brain at display time by `summarize()`. A cached copy would go stale exactly when it matters, and there would then be two answers to "is this brain built".
- `forget()` removes an entry and never a file. `brain forget` and the app's `d` key sit next to navigation keys; deleting a client's knowledge base is something a person should have to do with `rm`, deliberately. The tests assert the files survive, and so does the smoke test.
- A registered folder that has moved or been deleted is reported as `missing`, not silently dropped — a brain vanishing from the list on its own is indistinguishable from a bug.
`scaffold()` calls `remember()`, so the list fills itself in as you work rather than needing to be curated. `visualizer_is_stale()` is here too: `graphify extract` writes graph.json and does **not** redraw graph.html (only `update` and `cluster-only` do), so after a full rebuild the picture is quietly the previous one. `project.open_graph()` redraws it with `cluster-only --no-label` — no model, no tokens — before opening it.

**`src/brainiphy_cli/app.py`** — bare `brain` (and `brain new`): the flow. It opens on **your brains** (`_brains_screen`), and opening one drops into `_brain_screen`, whose body *is* the seven steps — a checklist you run in place, which re-inspects and advances as steps complete. It replaced a flat action menu and a one-shot wizard, which between them meant three overlapping front doors and no single answer to "how do I drive this". Notes:
- Owns no operations. Each step's action calls the same `project.py`/`sync.py`/`actions.py` function the equivalent named command calls.
- The step list is **not** written here — it comes from `steps.inspect()`, and `STEP_ACTIONS` only maps a step's `key` to how it is performed. Adding or reordering a step stays a single edit in `steps.py`; the flow follows.
- Steps stay reachable out of order on purpose. A new brain wants the sequence; a brain six months old wants "add one more source", and making it walk the flow to get there would be worse than the menu this replaced.
- `_prepare()` scaffolds a freshly chosen folder *before* the checklist appears, so picking a folder lands you on "Add data sources" rather than on a "Scaffold the project" checkbox. Choosing where the brain goes and preparing it are one intention; it is idempotent, writes only registry.yaml and the two ignore files, and prints what it did. Step 2 stays in the checklist for `brain init` and for re-running it. (This reverses an earlier rule that the flow must never perform a step implicitly — the checkbox was the first thing a new user hit and it read as busywork.)
- `SOURCE_KINDS` labels a source by **what it is** — `local folder`, `preset`, `http api`, `url`, `custom` — not by a sentence about it, and those strings match the `type` recorded in registry.yaml, so the label you pick is the label you see in every later screen. Each carries a badge (`ready to run` / `needs code` / `one-off`) because whether a choice leaves you with a working connector or with homework is what you want to know *before* choosing.
- `_choose()` takes `(label, hint)` or `(label, hint, badge)` plus an optional `intro`; the source screen passes `_registered_summary()` as the intro so adding a source visibly lands somewhere. Hints go through `_append_wrapped()` for the same reason the step explanations do.
- No screen is a dead end. Step 4 used to print two `$EDITOR` lines and stop — it now opens the connector in `$EDITOR` or runs the API probe. `_run_probe()` invokes the script with `sys.executable`, **not** its `#!/usr/bin/env python3` shebang: `brain` may be installed under an interpreter `env python3` does not resolve to, and then every connector dies on `import brainiphy_cli`. `sync.py` runs them the same way for the same reason.
- The front door is the brains list, with two shortcuts past it: a path argument, and standing in a brain already. Both then `remember()` it, which is how brains created before the list existed get onto it. "Change project" is gone from the tools menu — going back to the list is `b` on the checklist, because that is navigation rather than a tool.
- An empty list is not a screen worth drawing: with no brains there is exactly one thing anyone can do, so `_brains_screen` goes straight to creating one.
- `_forget_brain()` spends its whole screen saying what removal does *not* do, because the question it has to answer before it asks anything is "am I about to delete a client's data".
- `_append_wrapped()` exists because Rich wraps to the panel width but starts continuation lines at column 0, so a step's explanation collides with the list above it. Wrap against `ui.out.width - ui.FRAME_CHROME - indent` instead.
- Actions render through `ui.framed()`, which boxes their output. `sync` deliberately does not — nothing appears until a framed block ends, and watching a sync run matters more than the border.
- The credentials screen reads `SECRET_ITEM` out of the connector's `sync.py` rather than assuming `secret_item_name()`; a connector may legitimately point at a differently-named item, and writing the conventional one instead would store a credential the script never reads.
- Refuses without a TTY (`picker.is_interactive()` **and** `keys.supported()`), same as `brain new`.

**`src/brainiphy_cli/keys.py`** — single-keypress reading via termios/tty, for the menu's arrow navigation (`prompt.py` reads whole lines and cannot do this). Restores terminal settings in a `finally` on every path — leaving a shell in raw mode looks like a broken terminal, which is far worse than a broken menu. In raw mode Ctrl-C arrives as byte `0x03` rather than SIGINT, so it is re-raised as `KeyboardInterrupt` to keep cancellation handling uniform. Three things here are load-bearing and all three were found by testing it under a real pty, not by reading it:
- `tty.setraw(fd, termios.TCSANOW)` — the default `TCSAFLUSH` **discards pending input**, and the menu re-enters raw mode between every keypress, so anything typed while it repaints would vanish.
- `os.read(fd, 1)`, never `sys.stdin.read(1)` — `sys.stdin` buffers in userspace, so a whole escape sequence arriving at once sits in that buffer, `select()` on the fd reports nothing pending, and an arrow key is misread as Esc plus two stray characters. Holding an arrow key down does precisely this.
- `_pushback` — the byte read while disambiguating `Esc` from an escape sequence has already left the fd and cannot be un-read, so Esc-then-another-key would swallow the second key.

**`src/brainiphy_cli/actions.py`** — the interactive operations a step performs (`add_preset`, `add_local_folder`, `add_url`, `add_api`, `add_custom`, `ensure_graphify`, `_store_secret`) plus the `Cancelled` exception and the prompt wrappers that raise it. This was `wizard.py` until the flow moved into `app.py`: the step *ordering* went with it, the operations stayed. It must not import `app.py` — the dependency runs one way. Two rules earned by watching people get stuck: `add_local_folder` **browses** with `picker.pick_project_dir()` rather than demanding a pasted path (`/` inside the picker still accepts one), and `add_url` calls `ensure_graphify()` when graphify is missing instead of erroring out — being sent back to step 1 with no way to act from where you are is the shape of dead end this flow is meant not to have.

**`src/brainiphy_cli/project.py`** — every operation performed *on a target project*: `scaffold()`, `create_connector()`, `connect_claude()`, `schedule()`, plus the registry read/write helpers, `find_exe()`, and the connector-type vocabulary (`LOCAL_FOLDER`/`HTTP_API`/`CUSTOM`, `type_label()`). `create_connector()` records the kind it built as `type:` in registry.yaml — a preset stores its own name (`gohighlevel` identifies a source far better than the generic `http api` would), everything else stores one of the three constants. `type_label()` falls back to reading the generated script (`MIRROR_SOURCE` → local folder, `BASE_URL` → http api) so brains created before the field existed don't render a column of dashes; keep that fallback when adding a type. `create_connector()` picks one of four templates (`preset` → `mirror` → `api_base` → the bare stub) and fills them in through `set_constant()`, which rewrites a whole `NAME = …` line rather than doing string surgery on a placeholder — so a value only has to be a valid Python literal, not escape-safe inside quotes. `--var` is applied last and can therefore override a computed default such as `SECRET_ITEM`. cli.py, app.py and actions.py all call these. Each prints its own progress through `ui` and returns a plain bool/path; exit codes are cli.py's job.

`graphify_install_argv()` / `graphify_install_command()` are the only way to name a graphify install, and there are four callers (steps.py step 1, `actions.ensure_graphify`, `sync.find_graphify()`'s error, `cmd_init`'s warning) precisely because they used to each hardcode `pip3 install --user graphifyy` and were wrong in the same way. `brain sync` finds graphify by PATH lookup and shells out to it, so graphify and `brain` must live under one interpreter — and a bare `pip3` is whichever one is first on PATH. The failure is silent: the install succeeds and a later sync reports graphify missing on a machine where it is installed. Hence `sys.executable`, with `--user` added *only* outside a venv (PEP 668 refuses a bare install into a Homebrew or system Python; inside a venv pip refuses `--user`). `sync.py` imports this lazily inside the function — project.py imports sync.py, and a module-level import would cycle, same as `type_label()` in `run()`.

**`src/brainiphy_cli/prompt.py`** — `ask` / `confirm` / `choose` / `ask_path`, on the same Rich console as `ui` (a prompt drawn on a different console doesn't line up with the output around it). Every one returns `None` when the user hits Ctrl-C/Ctrl-D, so cancellation is an ordinary value instead of an exception at each call site. `ui.py` stays output-only.

**`src/brainiphy_cli/ui.py`** — the single Rich `Console` pair (`ui.out` / `ui.err`) plus the icon helpers every other module prints through: `step/ok/info/warn/error/hint/header/table/working`. Rules worth keeping:
- Messages are built as `rich.text.Text`, never markup strings, and `highlight=False` — connector names and paths come from user-written files and a stray `[` would otherwise be parsed as a markup tag. Use `ui.cell()` for table cells for the same reason.
- `ui.error()` is the only helper that writes to stderr; keep failures there so `brain sync` stays pipeable.
- Subprocess output (graphify, connector scripts) goes through `ui.raw()`, which disables markup/highlight and uses `soft_wrap` so tracebacks stay copy-pasteable.
- `cmd_secret_get` deliberately uses a bare `print()` — the value is meant to be piped, so it must stay unstyled and alone on stdout.
- Rich already drops color for non-TTY output and honors `NO_COLOR`; don't add a `--no-color` flag for it.
- `FRAME_CHROME` is what `app_panel()` costs horizontally: two border columns **plus its padding of two on each side**, so 6, not 4. It was 4, and every paragraph wrapped by a caller (`_append_wrapped`) or by `framed()` was two columns too wide — it wrapped against the terminal and then again against the border, which reads as random ragged lines.
- `framed()` is how the menu puts the whole app in a box without every command knowing about it: it captures **both** consoles (so a `ui.error()` on stderr lands inside the border rather than escaping it), narrows them by the panel's 4 chrome columns first (otherwise text wraps to the terminal width and then wraps again inside the border), and restores everything in a `finally` so a raised exception still prints what was produced. `working()` no-ops while capturing — a spinner would only write animation frames into the captured text. Don't wrap long-running work in it: nothing appears until the block ends.

**`src/brainiphy_cli/sync.py`** — the orchestrator `brain sync` calls. Deliberately has no notion of "connector types" *at run time*: every connector is just an executable script conforming to a contract (see below), so adding support for a new kind of data source means writing a new `sync.py` in the target project, never extending this module. The `type:` field in registry.yaml is display metadata only — `project.type_label()`, imported lazily inside `run()` to draw the `--dry-run` table. Nothing here branches on it, and nothing should start to. Key logic:
- `load_registry()` reads `<project>/connectors/registry.yaml`.
- `is_due()` / `_mark_ran()` track last-run timestamps per connector in `<project>/connectors/state/<name>.json` — this is how polling intervals are enforced across separate `brain sync` invocations (e.g. from a LaunchAgent). Anything unreadable there means *due*: one redundant run is the cheap failure, a connector frozen forever is the expensive one. `TypeError` is in that except clause because a naive timestamp cannot be subtracted from an aware one, and it used to take down the whole sync before any connector ran. `run()` likewise skips a registry entry with no name instead of raising — `registry.yaml` is a file people edit by hand.
- `run()` shells out to each due connector's `sync.py --out <project>/raw/<name>/`, then calls `build_graph()` once at the end if anything actually ran or `full=True` (not on every invocation — avoids needless rebuilds).
- `build_graph()` picks between two graphify commands that are **not** interchangeable: `graphify extract` (full pass, the only one that indexes documents, needs an LLM backend) on the first build and on `--full`, `graphify update` (code-only local AST, no key) after that. On a document corpus `update` is not literally a no-op — it rebuilds, adding structural nodes and merging the backed-up semantic layer — but it performs **no semantic extraction**, so a document added since the last extract lands in the graph as a file node and never as an entity. Only `extract` reads documents. The extract pass always gets `--no-gitignore` — graphify honors `.gitignore`, which lists `raw/`, so without the flag it skips the whole corpus and reports an empty project. `update` does **not** get it, and must not: `graphify update` accepts only `--force` and `--no-cluster`, so hoisting either flag out of the branch breaks every incremental sync. It also detects the "no LLM API key" failure and prints the ways out instead of a bare non-zero exit.
- `resolve_backend()` decides the `--backend` for the *extract* pass only (`update` has no model in it and rejects the flag): explicit `--backend` wins, then any configured API key defers to graphify's own detection, and with nothing set it falls back to `claude-cli` when the `claude` binary is on PATH. That backend shells out to `claude -p` and bills the user's Claude Code Pro/Max subscription — graphify's `detect_backend()` deliberately never returns it (it runs a program instead of reading a key), which is exactly why the choice has to be made here. Keep `_BACKEND_ENV_VARS` in sync with graphify's `llm.BACKENDS`: it only gates the automatic fallback, so a stale entry means either overriding a key the user set or missing the free path. There is **no ChatGPT-subscription equivalent** — graphify has no Codex-CLI backend, and `openai` needs a key or an OpenAI-compatible `OPENAI_BASE_URL`; don't add a shell-out to `codex` here without a graphify backend to receive it.
- `find_graphify()` resolves the `graphify` binary via PATH then falls back to the current interpreter's `--user` site bin dir.

**`src/brainiphy_cli/httpclient.py`** — the network layer generated API connectors import (like they already import `frontmatter`/`keychain`). `HttpClient` + the `NoScope` exception. Four things are baked in because each was learned by getting it wrong against a live API, and each fails *silently* rather than loudly:
- A non-default `User-Agent`. urllib's `Python-urllib/3.x` is banned by the WAF in front of several SaaS APIs (Cloudflare error 1010) — a 403 that never reaches the vendor and reads like an auth problem.
- One network entry point. `paginate()` fetches the next page through the same `request()` as the first, on purpose: the bug it exists to prevent is a second bare `urlopen` for `nextPageUrl` that skips all the retry and error handling.
- Retries on 429/5xx *and* on transient network faults (DNS, TLS handshake, dropped read). Connectors run unattended under launchd, where a blip must not become a stale graph.
- 401/403 raises `NoScope` rather than erroring. Missing scope is the normal shape of a vendor token, not a failure.

**`src/brainiphy_cli/collect.py`** — the run loop for connectors that pull more than one kind of object. A connector declares `Collector(name, subfolder, fetch)` entries and calls `collect.run()`, which gives it `--probe` (report what the credential can read, write nothing), `--only`, per-object isolation, and an exit code that distinguishes "no scope" (0, normal) from a real failure (1). Collectors run in list order and may depend on it — e.g. GHL's pipelines collector fills the id→name lookup its opportunities collector reads, so a stage renders as `"Awaiting payment"` and not `f7a80aa4-…`. Order the list accordingly and degrade gracefully when the earlier one had no scope.

**`src/brainiphy_cli/presets/`** — finished connectors for systems brainiphy already knows, installed with `--preset <name>`. `__init__.py` holds the `PRESETS` registry (`Preset` + the `Variable`s the installer must supply); each `<name>.py` is a complete connector copied *as text* and never imported, so the `CONST = "REPLACE_ME"` placeholders in it are fine. Adding one is: drop the file, register it. `gohighlevel.py` is the reference implementation — a preset keeps its own vendor `SOURCE_SYSTEM` (so records carry the same provenance across projects) rather than being renamed to the local connector name.

**`src/brainiphy_cli/api_template.py`** — the template for a REST API with no preset (`--api <base-url>`). Thin on purpose: `HttpClient` and `collect.run()` do the plumbing, and what's left is one `collect_*` function per object. Keeps a `raise NotImplementedError` so `steps.py` still detects it as unfinished.

**`src/brainiphy_cli/mirror_template.py`** — the folder-mirroring template, copied by `create_connector(..., mirror=<folder>)`. Unlike `connector_template.py` it is complete: an `rsync -a --delete` of a local folder into `--out`, with `MIRROR_SOURCE` substituted as a `repr()`'d literal. Mirroring rather than symlinking is forced by graphify (`follow_symlinks=False`, no CLI flag); `--delete` is what makes re-runs idempotent instead of leaving stale nodes behind.

It then converts what graphify cannot read. graphify indexes `.md/.mdx/.qmd/.skill/.txt/.rst/.html/.yaml/.yml`, `.pdf`, images and `.docx/.xlsx` (`detect.py`) and **silently skips everything else** — so a folder of CSV and JSON exports was being copied into the brain and ignored without a word: `brain sync` said "graph rebuilt", the folder looked full, and the graph had one node. Measured on a six-file folder: 2 indexed before, 7 after. Rules here:
- `NATIVE_EXTENSIONS` is never converted. Turning a `.docx` into our own Markdown would put a worse copy of it in the graph than graphify's own conversion does.
- A table becomes **one record per row**, not one document holding a table, because the graph wants entities it can relate. `MAX_ROWS_PER_TABLE` caps it and the summary says when it bit; `field_name()` turns `Importe (€)` into `importe` so the frontmatter is queryable and cannot break the YAML.
- Records go under `--out/_converted/`, and that folder is `--exclude`d from the rsync. It has no counterpart in the source folder, which is precisely what `--delete` removes — without the exclude the records are written and deleted again on every run. It is wiped and rebuilt each run instead, so a row deleted at the source stops being a node.
- Whatever is left (`.numbers`, `.key`, a video) is **named in the summary**. These files are in the brain's folder and will never be in its graph, and nothing else in the tool would tell you. Worth knowing: graphify also drops `.key` as a suspected private key.
- The generated connector imports `brainiphy_cli` (for `frontmatter.write_record`), so it must be run with the interpreter `brain` is installed under, never a bare `python3`. `sync.py` uses `sys.executable`; `scripts/smoke.sh` reads the shebang off the `brain` console script.

**`src/brainiphy_cli/connector_template.py`** — the fallback template, used when no `--preset`/`--mirror`/`--api` fits (a database, a local export, anything that isn't an HTTP API). Reach for `--api` first for anything REST — a connector that hand-rolls `urllib` is re-introducing the four bugs `httpclient.py` exists to prevent. This file also states the contract every connector script must satisfy, whichever template it came from:
- Accept `--out <dir>`, write normalized Markdown+frontmatter via `frontmatter.write_record()`.
- File names are a stable slug of the remote record ID, so re-runs overwrite in place rather than duplicating graph nodes.
- Exit 0/non-zero, human-readable summary on stdout.
- Read credentials only via `keychain.get_secret(<item>)` — never accept a secret as a CLI arg or hardcode one (shell history / process listings / launchd logs would leak it).
- Implementing a new source means filling in `fetch_records()` in the generated file — nothing else in the template should normally change.

**`src/brainiphy_cli/frontmatter.py`** — `write_record()` / `slugify()` / `yaml_str()`. Produces the same Markdown+YAML-frontmatter shape graphify's own `graphify add` produces, including the same hostile-string escaping (mirrors graphify's `ingest.py _yaml_str`, since a connector might pipe in untrusted field values like a CRM record title). Any connector-generated file must go through this, not hand-rolled YAML.

**`src/brainiphy_cli/keychain.py`** — thin wrapper over `/usr/bin/security` (macOS Keychain generic passwords). `get_secret()` is the only thing connector scripts should call; `set_secret()` is for `brain secret set` and the app's credentials screen. Secrets never touch `registry.yaml` or chat context — this boundary is intentional, don't add a code path that lets a secret value flow through an argument or a file brain writes. Two things here are load-bearing and both were verified against a throwaway keychain (`security create-keychain`), never the login one:
- `set_secret()` passes a bare `-w` **last** and writes the value to `security`'s stdin, twice (it asks for a confirmation). Never `-w <value>`: argv is readable by any process running as the same user for the life of the command, and it also reaches shell history and launchd logs. `security`'s own usage text says so. The module did pass `-w <value>` until it was fixed, which meant it broke the one rule it exists to enforce.
- The write is confirmed by **reading it back**, because the exit code cannot be trusted: `security` returns 0 on paths that store nothing, and on one that stores a *different* value (give it a value and a confirmation that disagree). Reporting a credential as saved when it is not moves the failure to the connector's next run, where a missing token reads as an auth problem. A value with a line break is refused up front for the same reason — it would arrive as two disagreeing answers.

**`src/brainiphy_cli/picker.py`** — the directory browser (`pick_project_dir()`), used by `cmd_init` with no path, by the app when the cwd is not already a brain, and by `actions.add_local_folder` to choose a source folder. This is the first screen most people see, so it wears the same chrome as the app: arrow-key navigation inside `ui.app_panel`, scrolling viewport, and an "already a brain" marker next to folders that are scaffolded. It only creates a folder after an explicit confirmation.

The two things a person came here to do — "use this folder", "create a new one" — are **rows of the list**, pinned above the folders, and `↵` activates whichever row is highlighted. They used to be the hidden keys `a` and `n` while `↵` descended into a folder, which meant the most obvious key did the one thing nobody wanted and selecting a folder was undiscoverable. `→` is what descends now; `a`/`n` still work for anyone who learned them. `_action_rows()` decides how many pinned rows there are, and every cursor↔folder index conversion goes through `len(actions)` — do not hardcode 2, `allow_new=False` drops one.

`pick_project_dir()` takes `title` / `purpose` / `allow_new` because it now picks two different kinds of folder: `purpose` is the noun in the confirmation ("Use ~/x as the **brain**?" vs "as the **source**?"), and `allow_new=False` hides the create-a-folder row when the caller needs a folder that already has content in it.

Two implementations, and the second is not dead code: `_pick_navigable` needs raw mode, so when `keys.supported()` is false it falls back to `_pick_typed`, the original numbered/typed loop that needs only line input. Losing the picker altogether would make `brain init` with no argument unusable.

`cmd_init` calls it *only* when `picker.is_interactive()` (stdin **and** stdout are TTYs); piped or launchd-driven invocations keep the old behavior of defaulting to the cwd, so the argparse default for `project` is `None`, not `"."` — don't restore `"."` or the interactive path becomes unreachable.

**`src/brainiphy_cli/launchd_template.plist`** — placeholder-substituted (`__PROJECT_SLUG__`, `__BRAIN_EXE__`, `__PATH__`, etc.) by `cmd_schedule` into `~/Library/LaunchAgents/com.graphify.sync.<slug>.plist`, then optionally loaded with `launchctl bootstrap`. Generated output, not meant to be hand-edited — change the template and regenerate instead. The scheduled command is `brain sync <project> --full`, and the `--full` is load-bearing: the incremental pass never indexes documents, so without it an unattended brain mirrors new files in and reports success while the graph stops being current. It is also cheap — `graphify extract` is gated by its own manifest and semantic cache, measured at ~1s and zero tokens on a corpus with nothing changed. `__PATH__` comes from `project._agent_path()`: launchd gives a job only `/usr/bin:/bin:/usr/sbin:/sbin`, so the dirs holding `brain`/`graphify`/`claude` are resolved while `brain schedule` still has the user's environment and pinned into the plist — without `claude` on that PATH a scheduled `--full` sync loses the subscription backend. Those dirs are deliberately **not** `resolve()`d: `claude` is a symlink into `~/.local/share/claude/versions/<version>/`, a directory that holds version-named files and no `claude` binary, so the resolved parent would be both useless and stale after the next update.

### Per-project generated layout

`brain init <project>` and friends produce, inside the *target* business/client project (not this repo):
```
<project>/connectors/registry.yaml       # which connectors exist + type + interval_minutes
<project>/connectors/<name>/sync.py      # one script per data source, from connector_template.py
<project>/connectors/state/<name>.json   # last-run timestamps, drives is_due()
<project>/raw/<name>/                    # connector output (normalized Markdown), graphify ingests from here
<project>/graphify-out/graph.json        # the built graph
<project>/.graphifyignore                # must list connectors/ — otherwise graphify's AST extractor
                                          # indexes the connector scripts themselves as source code
```
`.gitignore` vs `.graphifyignore` serve different purposes here, and they interact: `.graphifyignore` is the one graphify always obeys (its own gitignore-syntax-compatible parser) and is what keeps `connectors/` out of the index. But graphify also honors `.gitignore` unless `--no-gitignore` is passed — and `.gitignore` lists `raw/`, so any graphify call over a brain without that flag finds nothing at all. Verified empirically: `graphify extract` on a scaffolded project reports "found 0 code, 0 docs" without the flag and finds the corpus with it.

## Key constraints worth knowing before changing behavior

- graphify does not follow symlinks (`detect.py`, `follow_symlinks=False`, no CLI flag) — any code path that's tempted to symlink a local source folder into a project instead needs to physically mirror it (e.g. `rsync -a --delete`).
- `connect-claude --trust-desktop` must always be additive to `localAgentModeTrustedFolders` in `claude_desktop_config.json`, never a replace — and the config file must be backed up before every edit (see `cmd_connect_claude`'s backup-then-write pattern).
- `brain schedule` intentionally refuses to run when a project has zero registered connectors (`cmd_schedule`'s early check) — don't remove that guard, it exists because scheduling a sync loop with nothing to sync is a silent no-op that's confusing to debug later.