# Bring a brain to Sevra — the one-paste onboarding (for agents) You are an agent setting up a hosted brain for your person. The migration is the demo: first value lands on what they already have (notes, a vault, an export, a folder of documents) — never "connect tools first." Assume nothing on this machine beyond a shell, curl, and internet. ## 1. Install the two tools ```bash curl -fsSL https://www.sevrahq.com/install/dbmd.sh | sh # db.md, the open standard's toolkit curl -fsSL https://www.sevrahq.com/install/sevra.sh | sh # sevra, the hub CLI (signed, self-updating) ``` On Windows, both tools install natively with PowerShell (x64, with built-in emulation on Windows ARM64): ```powershell irm https://www.sevrahq.com/install/dbmd.ps1 | iex irm https://www.sevrahq.com/install/sevra.ps1 | iex ``` Load the standard: run `dbmd spec` and read it. It is short and it is the whole format. Every `sevra` command takes `--json` for machine-readable output. ## 2. Sign in — one browser approval, no key Just run it: ```bash sevra login ``` Your person's browser opens; they approve once; you get a session (stored 0600, never echoed) named after this machine. Nothing to mint, nothing to paste. If they do not have an account yet, that same browser step signs them up free (the home is free — hosted, always alive, not a trial). Headless or over SSH? `sevra login` prints a short code and a URL to open on any device instead. A stored key (`sevra login --key `, minted in Dashboard → Account) still works for scripts and CI. ## 3. Migrate what they already have Take the messy folder as it is. Build a valid store from it: - One markdown file per record. `sources/` holds evidence as-found (documents, exports, transcripts — immutable); `records/` holds what you distill (facts, decisions, notes — with `type`, `summary`, `created`, `updated`, and an `id` minted by `dbmd write`). - Wiki-links (`[[records/...]]`) are the relationships. - Binary evidence (PDFs, images, recordings, data files) rides too — as **assets**, not markdown. Declare each file in its wrapper record's `assets:` frontmatter (store-relative paths), then run `dbmd assets scan`: it hashes what is declared and writes the root `assets.jsonl` manifest. The manifest travels with every push; the bytes follow it (step 4). Undeclared binaries stay home — declaration is what makes a file part of the brain. - `dbmd validate --all` must report **zero errors** — fix every error it flags. Warnings are advisories: fix the easy ones, but a store whose `DB.md` documents accepted warning classes is healthy with them, and `log.md` is append-only — never rewrite history to appease a warning. - Answer one real cross-cutting question from the store before you push; if you can't, the migration isn't done. - Nothing to migrate yet? Interview your person: ten minutes of questions (who they are, what they're working on, what they keep re-explaining), then write the first records from the answers. A brain that starts with ten real records beats an empty one. ### Keep secrets out A multi-year folder accumulates live credentials — API keys, cloud access keys, app passwords, share links — often other people's. `sevra push` scans every outgoing file, contents and names both, and refuses on a match — naming files, never values (`sevra secrets scan` runs the same check read-only). Four exits, in order: 1. **Adopt markdown credentials into the brain vault.** Run `sevra secrets adopt `: it stores each value in the encrypted, brain-scoped vault before replacing the literal with an inert `$NAME` reference. It removes an exact quarantine entry only after the vault write is durable. Inspect the diff, run `dbmd validate --all`, then push the redacted files. Adoption requires a sync baseline. On a first migration, quarantine the flagged files, push the clean remainder once, adopt, then push again. Adoption is markdown-only; asset hits still need exit 2, 3, or 4. 2. **Keep verbatim files home** (0.2.5+): `sevra secrets quarantine ` marks each flagged file in `.sevralocal` at the store root. Marked files stay part of your brain locally — dbmd reads them, links resolve — but they never ride a push, and neither does the list itself. Add `--closure` to also mark files link-connected to what was flagged: the vault-shaped cluster with innocent names that keyword scans miss. Quarantine reports what this costs the HOSTED graph (0.2.8+): every incoming link to a kept-home file dangles up there, even though nothing changes locally. Keeping one raw export home can dangle thousands of `source:` links — when that number is large, exit 1 is usually the better trade. 3. **Edit it yourself.** Move the value to a password manager and keep a reference in the record. Sevra never edits your files; deliberate redaction is yours to make. 4. **Ship verbatim, as a last resort**: `--allow-secrets`. This puts the matched bytes in immutable brain history, retained backups, exports, and every permissioned copy. Use it only when the content is deliberately meant to replicate and that blast radius is acceptable. Know what each undoes. Kept-home is forward-only: the feed is append-only and snapshots are immutable, so a file that already rode a push stays in earlier snapshots — quarantine removes it from the next one and erases nothing. True erasure is `sevra delete` on the brain and a fresh push. Two name leaks the tools watch for you: derived catalogs stay home whenever `.sevralocal` is active (the hub rebuilds its own from what actually arrived), and quarantine warns when `assets.jsonl` declares a kept-home path by name. After the push, `sevra secrets status ` shows names that are declared, stored, or in use without returning values. Sevra also checks the hosted copy at ingest. The owner-only dashboard and MCP status report show credential-shaped filenames and content classes for review; the report never stores matched bytes and never rewrites the brain. ## 4. Push it home ```bash sevra create # a brain on the hub (--name for a display name) sevra push --brain # durable copy: R2 + feed + index — reachable, alive ``` **Push replaces.** A push makes the brain an exact copy of `` — files absent locally are removed from the hub copy. Aim twice at `--brain`. The hub refuses a push that would drastically shrink an established brain unless the push states `allow_shrink` (`sevra push --force`, 0.2.4+). **What rides how.** A push carries two cargos. The **pack** is the markdown store plus `assets.jsonl` — nothing else enters it. The **asset bytes** follow after the commit: `sevra push` (0.2.7+) asks the hub which declared hashes are missing and ships each through a content-addressed, checksummed upload — deduped, resumable (a re-push skips everything already present), and refused for any hash the ingested manifest does not declare. `--skip-assets` opts a push out. **Limits.** A canonical pack is capped at 512 MB of file content plus bounded ZIP headers / 65,535 files per push, with UTF-8 paths capped at 1,024 bytes. `sevra push` preflights the same numbers locally, so an over-limit store is refused before any upload spends bandwidth. Markdown compresses far under the compressed cap; what the 512 MB bound actually measures is raw markdown volume, and moving bulk payloads out of wrapper bodies into assets is the honest fix. Assets cap per file (2 GiB) and per account (the plan's storage allowance — `storage_cap` names it when it binds). A `507 hub_scratch_exhausted` answer is the hub's condition, not your pack's: the upload is kept, retry the commit in a minute. From here everything is incremental: work locally, push; query with `sevra query ` or `dbmd`; the full store is always exportable (`sevra export [dir]`) — markdown, manifest, and asset bytes restored beside it, SHA-verified — open files, never locked in. ### Use it on another machine ```bash sevra clone [dir] # first copy: records, assets, and a sync baseline sevra pull [dir] # refresh in place ``` `pull` refuses to overwrite local changes. Resolve them or use `--force` only when discarding them is intentional. `push` likewise refuses when the hosted brain advanced past this machine's baseline. Both operations use a durable journal and recover before network access if a previous process was killed mid-update. The vault is server-authoritative and follows the signed-in owner, so it does not need a device-to-device sync ceremony. Use `sevra secrets set|get|list|rm` for individual values. A normal export contains vault names only; explicit `sevra export [dir] --with-secrets` writes values into private mode-0600 `.sevra-vault.json`, making that export credential-sensitive. ## 5. Show it worked The migration is the demo. Ask your person for one question they actually care about, answer it from the pushed brain, then hand them their home: https://www.sevrahq.com/dashboard. Their brain is live there, always on. ## 6. Optional, when they want it - **Publish**: set `visibility: public` on chosen records + `sevra publish ` → a site at `.sevra.page`. Read https://www.sevrahq.com/docs/publishing.md first — it is the whole platform contract (pages, apps, audiences, the inbox, the engine, functions). - **Upkeep**: an `agent:` block on a record defines the work and its scope. BYO means your own AI runs it free forever. `engine: sevra` means the hub runs it with run credits on its configured schedule or when you start it from the dashboard, MCP, or `sevra run`. Rules that keep you honest: never invent facts during migration; sources are immutable; absent `visibility` is private, always; look at what you published.