orgchain/AGENTS.md

# AGENTS.md

Orgchain is lineage's app for creating and operating lineage holdings on Super Testnet's toy chain.

- Test-only, always: no mainnet funds, no hidden signing, no custody, and nothing presented as a real key.
- Lineage semantics live in one place, `src/orgchain/lineage.js`. The UI never interprets events itself, and every act
  is vetted by that reducer before it is signed. A new op means a reducer change, its tests and the README's table.
- The engine (`src/adapters`, `src/upstream`, `src/storage.js`, `src/miner.js`) is Super Testnet's. Compose with it
  rather than rewriting it, and keep its tests passing. Preserve upstream licenses and provenance. Its one local
  change is P2WPKH payments in `src/adapters/chain.js` (PROVENANCE.md); keep it small and tested.
- Money lives in `src/orgchain/money.js`: beats pay the holding being worked in, and sends stay inside a holding and
  spend SegWit coins only, so an inscription can never leave as change. Balances are read off the chain, never stored.
- Keys follow the tree (`src/orgchain/keys.js`): store roots only (one per holding, one per graduated org) and derive
  every other key from its position. Every act is signed by whichever key holds the authorizing inscription.
- A node's chain key is its account's BIP-86 Taproot key (`m/86'/1'/account'/0/0`); SegWit is BIP-84 at the same
  account and holds its money. Leaves are HKDF-SHA256 (salt `lineage/v0`) and must stay byte for byte with lineage's key tree page;
  `tests/keys.test.js` holds values read off that page.
- Secrets show only behind Reveal, reset on every selection, and match the key tree page byte for byte (the tests pin
  hashes of the page's own output).
- The page makes no network requests; keep it that way (the deployed CSP sets `connect-src 'none'`).
- Before shipping: `npm test`, `npm run build`, `npm run test:e2e`.