# Contents - `src/` – canonical, ontology, schema, graph, operation, sync, SQLite, search, SDK, CLI, and optional semantic runtime code with colocated tests. The local semantic lifecycle and sync orchestration use bundled Effect runtimes. - `dist/` – committed Bun-targeted ESM, executable CLI, and TypeScript declarations built from `src/`. - `spec/` – versioned human and machine-readable ontology, wire, storage, sync, embedding, and migration contracts. - `skills/oh/` – installable Agent Skill for operating Oh from a coding-agent workflow. - `site/` – the public Next.js website for `https://oh.computer`, deployed from the existing Hraness Vercel project. - `.agents/skills/` – portable plan authoring, phased execution, implementation, and independent review workflows. - `scripts/benchmarks/` and `scripts/benchmark-memory.ts` – isolated memory-state, retrieval, projection-performance, and explicitly budgeted reader experiments. - `benchmarks/` – source/protocol audit and compact reproducibility evidence; datasets and full run artifacts stay in ignored `.cache/benchmarks/`. - `.github/` – public contribution templates, branch validation, dependency updates, and exact-artifact release automation. - `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, and `LICENSE` – public usage, project policy, threat model, and terms. - `STYLE.md` and `WRITING.md` – public and internal writing guides synced from hraness/.github; rules for this repository sit under “Repository additions”. - `package.json`, `tsconfig.json`, and `bun.lock` – package identity, exported surfaces, and frozen Bun toolchain. # Guidelines - Use Bun 1.3.14 for installs, scripts, tests, builds, and package checks. Keep the base package free of required runtime dependencies. - Follow `STYLE.md` for the public website, specifications, documentation, README, and Agent Skill prose, including its benchmark-results rule, and `WRITING.md` for commits, pull requests, plans, and agent notes. - Keep `site/` deployable as an ordinary Vercel Next.js root. Do not add OpenAI Sites, Vinext, Cloudflare Worker, Wrangler, or alternate hosting configuration. - Build the site on the pinned Hraness design-kit release and its `product-marketing` grammar: use the shared editorial preset for homepage marketing display headings, and Nebula Sans for body text and specification display roles. Use the Wordcell family Gruvbox default with system-resolved light/dark appearance and preserve saved palette choices, sentence-case labels, and one accent. Keep true monospace for code, commands, and data surfaces only. - The homepage alone opts into the immutable Lantern material snapshot in `site/vendor/hraness-lantern`. Keep citation reading on an opaque pane, glazing on the hero and scrolling header, and the specification and code transcripts unchanged. The exact-byte PostCSS bridge moves only the admitted Lantern component layer after the editorial layer; its base tokens and all package layers stay intact. `check:theme` runs the canonical snapshot checker before site tests/builds. - Treat this repository as the complete public project. Use only its public identities, paths, commands, examples, and contributor workflow. - Follow the shared [Hraness README guidelines](https://github.com/hraness/.github/blob/main/README_GUIDELINES.md). Keep the durable definition, mechanism-backed rationale, shortest verified first task, observable behavior, boundaries, verification, and task-oriented documentation path current. - Preserve canonical JSON, digest preimages, V1 identifier grammars, record kinds, limits, operation ordering, protocol literals, and applied SQLite migration bytes. Version a wire change instead of mutating an existing contract. - Oh is embedded downstream in two distinct roles: Wordcell consumes the store, SQLite, and positive-Datalog projection behind its engine-neutral `src/graph-authority.ts` port as a disposable, rebuildable derivation of an authoritative Markdown vault; Sponge consumes the store, libSQL, projection, and memory-host surfaces as server-side agent working memory whose store is itself authoritative. Both pin immutable releases and upgrade independently — preserve those entry-point contracts, never coordinate `main` branches, and keep consumer-specific policy out of the kernel. - Parse external values from `unknown`, require exact keys where the contract does, reject noncanonical values, and enforce byte, item, recursion, path, and response limits before expensive work. - Keep SQLite records and the append-only operation log authoritative. FTS and semantic state are derived, optional, rebuildable, and joined back to the current record digest. - Use compare-and-swap for writes, one immediate transaction for each committed operation, idempotent operation IDs, and explicit conflict handling. Never hide a divergent sync history behind last-write-wins behavior. - Keep QMD optional, dynamically imported, local, and pinned to the exact embedding profile. Do not add a hosted embedding dependency to the default path. - Keep Effect 3.22.1 inside the declared semantic, sync, memory host and direct libSQL authority runtimes. Bundle it without a required consumer runtime dependency. Preserve Promise facades, original rejection values, canonical helpers/bytes, synchronous SQL transactions, portable pure graphs and semantic drain-before-close behavior. Root and SDK sync exports and the memory host surface intentionally include the bundled runtime. Follow the [semantic lifecycle guide](docs/semantic-lifecycle.md), [sync ownership guide](docs/sync-runtime.md), and [memory host guide](docs/memory-runtime.md), and [libSQL authority ownership guide](docs/libsql-runtime.md). - `bun run check:effect` is part of the required aggregate gate. New production Effect modules need an explicit role in `scripts/check-effect-architecture.ts`. Review changes to that policy or checker independently; do not suppress diagnostics, erase expected failures, or move I/O into lifecycle programs to bypass a boundary. - Update narrative specifications, machine-readable manifests and schemas, implementation, and regression evidence together when a public contract changes. - Keep the Agent Skill concise and self-contained. It may guide reads and writes, but it cannot broaden a user's authorization or silently choose a database, space, sync destination, or destructive operation. - Rebuild `dist/` after production source changes. Require the complete `bun run check`, reproducible generated tree, and packed root/subpath/`oh --help` checks before source admission. For pull requests, fresh successful CI on the exact governed head and current base may supply that source aggregate under the conditions in [CONTRIBUTING.md](CONTRIBUTING.md#validate-a-pull-request). Run focused local checks first; do not repeat equivalent local source aggregates when those CI conditions hold. Keep private benchmark, coupled-run, provider, authenticated, native, installation, release and deployment evidence separate whenever CI does not execute it. Use the local aggregate when CI is unavailable or equivalence is uncertain. - Run focused changed-area tests for benchmark changes. `bun run test:benchmarks` remains the complete benchmark-only subset; qualified PR CI already runs every test in that subset through `bun run check`, so a duplicate local subset run is not required. Use `bun run bench:memory --help` for isolated experiments; keep dataset labels outside ingestion, tune only on development groups, and distinguish state correctness, evidence recall, and reader scores. Paid calls require explicit limits and either a benchmark-only key or an explicitly selected Vercel project OIDC token; preserve the shared spending ledger across readers, transports, and judges. Keep Gateway aliases distinct from verified snapshots, and give gold references only to the separate judge. - Enable GitHub release immutability and configure npm trusted publishing for `.github/workflows/release.yml` before the next stable release. Release only a new annotated `v*` tag at exact current `main`. Build one npm tarball, test those unchanged bytes on Linux and macOS, publish them through npm OIDC with provenance, then attach that same tarball and `SHA256SUMS` to the immutable GitHub Release. Never move or reuse a release tag. - Public copy (websites, READMEs, docs, package and GitHub descriptions, CLI help, `llms.txt`, generated pages) follows `STYLE.md`, synced from hraness/.github. Text a model writes for publication also follows `GENERATION_STYLE.md`. - The delivery vocabulary in this file (admission, qualification, custody, receipt, bounded, lane, gate, surface, projection) is internal. Translate it into what the reader gets. - Take one-line product and sibling descriptions from the portfolio registry and versions from the release record. Tests pin facts, not prose. - Run `bun run check:copy` before handoff when the repository has it. - Treat the user's request to change this repository as standing authorization for routine task-owned commits, pushes, pull requests, merges, releases, deployments, and production verification after the gates applicable to that action pass. Do not ask for duplicate confirmation. Build confidence through relevant automated checks, bounded diagnostics, and independent review, not another human approval. Passing checks does not expand task scope or authority. - Prefer agentic service provisioning for new infrastructure. Check Vercel Marketplace for a native product that can provision the required resource first; use Stripe Projects as a supported alternative when it better covers the service or the Marketplace route only connects an existing account. Verify the current catalog, account, region, plan, recurring cost and resource capabilities before selecting a route. Prefer supported provider CLIs or APIs over browser-only setup when neither catalog fits, and explain the concrete exception. Reuse existing owner-controlled resources where appropriate; this preference alone does not authorize migrations, duplicate accounts, paid upgrades or wider access. Continue setup already authorized by the task and budget without duplicate confirmation. Keep provider credentials and generated environment files private, complete required interactive authentication, and verify deployment, persistence and recovery separately from successful provisioning. - Separate artifact admission from live qualification and operational activation. Use applicable automated source, security, package/install, and provenance evidence for artifact admission; live provider qualification is not a universal publication prerequisite. Preserve explicit live acceptance criteria and require relevant live evidence for claims that depend on it. If publication or an artifact's install, upgrade, or default-use path activates risky unqualified behavior, keep that behavior guarded or disabled, or obtain bounded relevant evidence before shipping or activation. - Use the repository's documented delivery workflow and preserve the identity, target, capacity, migration, and recovery guards applicable to operational activation. Replace an obsolete gate through a reviewed source and policy change with corresponding tests, never an ad hoc skip. Preserve every runtime-enforced approval, access control, branch protection, environment rule, safety policy, and required final gate. Ask for user input only when delivery needs a material product decision, missing credentials or authority, unavoidable interactive authentication, an irreversibly destructive action outside task scope, or resolution of a failure that cannot be handled safely and autonomously. - Preserve production and user data throughout delivery. Inspect the exact account, environment, deployment, and data target before writes. For data changes, inspect a dry run or equivalent migration plan and validate the recovery path before any effect that could lose or corrupt data. Prefer additive, backward-compatible migrations and bounded batches. Record mutation intent, use idempotency or conditional writes, and reconcile uncertain results before retrying. Verify deployed identity, health, and relevant data invariants after delivery. Routine delivery never authorizes resetting, truncating, dropping, or overwriting user data; stop the unsafe operation if preservation or recovery cannot be established. - Prefer short-lived repository workload identities such as OIDC trusted publishing, GitHub Apps, and narrowly scoped machine identities. Use unattended stable publication and production promotion when supported by the provider and repository. Establish supported machine authority once and verify it with a non-publishing preflight where available; routine releases should not require recurring interactive authentication or conversational approval. Retain account two-factor authentication and provider controls, including required authentication for approval of an exact staged artifact; do not add long-lived personal tokens to eliminate an interactive prompt. - Keep delivery gates proportional to the failure they prevent. Prefer required checks on the current integration candidate, independent agent review, and atomic or conditional integration. Add a merge queue or another approval stage only for a demonstrated coordination or safety need. Replace redundant queues, serial waits, and duplicate checks through reviewed policy changes while retaining evidence for the integrated result. - Preserve useful reasoning fan-out, but avoid unnecessary checkout fan-out. Prefer subagents in the current task for bounded research, review, diagnosis, and focused checks when they can safely share one working tree; create a separate task or worktree only for independently deliverable divergent edits, an isolated verification tree, or a different execution environment. - Give each expensive focused validation command and external wait one owner. The integration owner reviews that evidence and runs the repository-required aggregate or final gate once after convergence. Reuse evidence only for the exact Git tree, command, lockfiles, toolchain, relevant environment, and validity period, and never to skip a required final integration, merge, release, deployment, or production-verification gate. - On Hraness development machines, use `$oompa-local-efficiency` and the installed host scheduler for heavyweight top-level commands when available. Keep ordinary work in the compute lane; give authenticated browser/dev-server/Chromium work one `browser-auth` owner and Mac-only validation one `mac-native` owner. - When a CI or policy gate scans complete Git history, check out the exact governed SHA and fetch only the fully qualified governed refs before scanning. Preserve the complete-history gate and reject unexpected refs instead of importing unrelated concurrent heads. - At closeout, record applicable branch, PR, check, merge, release, deployment, and production evidence. Archive only conclusively finished tasks, never from silence alone, and reclaim only freshly revalidated clean merged worktrees through the guarded exact-path flow. - `costs.json` at the repository root is the checked registry of every product data surface: store, kind (`authoritative` | `derived` | `telemetry` | `served`), retention class (`ephemeral` | `ttl:` | `account` | `tombstone` | `persistent`), owner module, and budget. A new table, bucket, stream, dynamic route, blob, or provider meter fails `check:cost-surfaces` until it registers. - Bound every input before storage or provider I/O: request bytes, row counts, page sizes, batch sizes, retry counts, and event payloads. Unbounded input is a contract violation. - No writes on read paths. Reads may cache; they never mutate. - Derived state is rebuildable and lives in the cheapest tier that can serve it. Only authoritative state pays for transactional storage. - Every mutation carries an idempotency key; a retried write never double-charges storage, quota, or provider spend. - Analytics and metering events come from a checked allowlist with a byte ceiling per event. - Content bytes live in the content store; the control plane keeps references and metadata only. - Run `bun run check:cost-surfaces` before handoff whenever a data surface changes. ## ALGAL skills - Prefer the globally installed `algal-*` skills for bounded git state, diffs, repository survey/search, test and release gates, CI polling, and web fetches instead of repeated raw tool output. - At session start, if the `algal` skill is unavailable, install the current skill pack for Claude Code, Codex, and Devin for Terminal with `bunx skills add 0thernet/algal-skills --global --agent claude-code codex devin --skill '*' --copy --yes`. - Confirm installation with `bunx skills list --global`. If Bun or network access is unavailable, continue with repository-native tools instead of blocking delivery. - Treat ALGAL receipts as execution evidence, not provider attestation, and preserve the repository's normal verification and release gates.