Ethos

Why Outcrop is built the way it is. The BRIEF says what to build; this says what to protect. When a future decision is ambiguous, it should lose to this document, not win against it.

Outcrop exists for one stake: managing knowledge — and managing includes authorship and curation, not just retrieval. A knowledge system you can query but not comfortably write in is a warehouse. A system you can write in but not trust is a junk drawer. Outcrop's bet is that you get both by refusing to take the files away from their owners.

The principles

1. Your files are the database

The storage engine is a folder of markdown files — not an import of your files, not a mirror, not a cache. There is nothing to export because nothing was ever taken. Leaving Outcrop costs zero bytes: what remains is a readable, diffable folder that Obsidian, grep, and GitHub understand. Every feature must survive the question "does this still work if the user just opens the folder?"

2. Bytes are sacred

An UPDATE that touches one frontmatter field leaves every other byte identical — not "semantically equivalent," identical. The system never reserializes what it didn't change, because those bytes are someone's authorship: their spacing, their ordering, their comments. This is a property test, not a promise (document_props.rs: edit one field, assert byte-identical remainders, 128 cases per property).

3. A violating file is never corruption

Schemas are constraint tools, not gatekeepers. A record that breaks the rules is a valid file and a flagged record — visible, queryable (_flagged), fixable — never rejected data, never a quarantine. Policies (ignore | warn | block) express how loudly to object at write time; they never license destroying or refusing to read what exists. Knowledge is messy before it is clean; the system must hold it during the messy part.

4. External writers are first-class

Obsidian, any editor, git pull, Finder, other agents — these are not threats to defend against; they are co-authors to detect and fold in. The watcher reindexes external edits; conflicting ones surface as ordinary, resolvable conflicts against snapshot reads. Never lockout, never a stale lock file, never "please close the file in the other program."

5. Honesty over promises

Say exactly what the system guarantees and no more. Snapshot-read isolation over a filesystem shared with humans — documented, not upgraded by marketing into serializability. Coverage numbers, deviations, and open questions live in the RUNLOG in public. When the honest answer is "not supported yet," the system says that, cleanly, instead of approximating.

6. Meet people in their own vocabulary

Git is the engine, never the interface. People manage Scenarios, pin Snapshots, Propose changes, Keep mine or theirs, browse History, Restore. Nobody resolves <<<<<<< markers; conflicts are record-scoped and field-level, because that is the granularity at which a human actually holds the problem. This is an API rule enforced in the transaction layer's public surface, not a coat of UI paint.

7. Ride standards; win by citizenship

OKF for the file convention ("riding the standard, not inventing a rival"), SQL for queries, LSP for editors, MCP for agents, protobuf for the wire, GitHub as the registry. Outcrop does not ask ecosystems to come to it; it shows up conformant and useful inside the ones that exist. The corollary is discipline: no plugin system, no bespoke connectors — when federation comes, it rides ADBC/Arrow Flight, not an invented protocol.

8. One content model — everything is a record

Dashboards are records. Skills will be records. Themes will be records. The bundle index is a record. The system's own architecture documentation is a bundle of records (/bundle) that its own validator checks in CI. Whenever a feature wants its own persistence format, the answer is the same question asked louder: why isn't this a record? One model means every capability — diff, merge, scenario, query, search — multiplies across every feature for free.

9. Claims are tests

Red-green per feature. Crash safety is a SIGKILL mid-transaction in a test harness, not a paragraph. Losslessness is a property test. The corpus plants deliberate violations and the suite asserts exactly those are flagged. Dogfooding is CI: every build validates the self-describing bundle with the binary it just built. A claim that can't be demonstrated gets written down as an open question, not asserted.

10. Authorship should be a pleasure

Curation is not an afterthought bolted to a query engine. Writing, editing, annotating, resolving, and pruning knowledge should be enjoyable and efficient — on the canvas, in the CLI, in whatever editor the person already loves. The measure of the authoring surface is whether someone wants to tend their knowledge with it. Guardrails should feel like a spotter, not a turnstile: validation that helps you finish, never a modal that stops you.

11. Humans and agents are co-equal authors

Agents get the same tools people do — query, upsert, validate, scenario, merge — through MCP, with no privileged side door. What makes that safe is architecture, not trust: transactions stage agent writes as reviewable diffs, policies flag what's questionable, and History records who did what. The same properties that make external human edits safe make agent edits safe. Provenance and trust metadata (OKF's generated, sources, verified) are data Outcrop can validate and query — accountability as a first-class column.

12. Defer deliberately; stop and stabilize

Scope is a design tool. The do-not-do list is as binding as the feature list; milestones stop and stabilize rather than half-finish the next thing. Deviations from plan are legitimate — and get logged (RUNLOG) with reasons and revisit triggers, so deferral never silently becomes abandonment.

Where the ethos is enforced

Values that live only in prose decay. Each principle above is wired to a mechanism that fails loudly when violated:

Principle	Enforcement
Bytes are sacred	proptest byte-identity property, outcrop-store
Never corruption	flagged-record tests over planted corpus violations
External writers first-class	watcher + concurrent-writer test suite
Honesty over promises	RUNLOG deviations/open-questions convention; clean "not supported" errors
Human vocabulary	no git terms in outcrop-txn/server public APIs (reviewed surface)
Ride standards	OKF spec vendored + weekly watch workflow auto-PRs drift
One content model	canvas-as-record round-trip tests; bundle-as-records in CI
Claims are tests	80% coverage gate; SIGKILL crash tests; red-first discipline
Co-equal authors	MCP tool parity with gRPC; policy checks on every write path
Defer deliberately	RUNLOG revisit triggers (e.g. registry strategy)

Provenance

Distilled 2026-07-30 from BRIEF.md (the non-negotiables), the overnight build's RUNLOG, and the founding conversation's stated intent — including, verbatim in spirit: "the whole stake is about managing knowledge, and part of managing is authorship and curation; this should be an enjoyable and efficient experience." Also queryable as records: bundle/ethos/.