Data overlay structure

An annotated template of the private .heading-os-data repository — the partner of the engine (code-only) clone. Everything below is a generic structure a new operator recreates; no real private content is shown.

Engine / data separation

HEADING OS splits one operator workspace into two git repositories:

Engine (.heading-os) — code only: skills, rules, scripts, daemons, config templates, docs. Shareable, eventually public. No real data, secrets, or PII.
Data overlay (.heading-os-data, documented here) — all real data plus every generated artifact: CRM, knowledge, context, threads, plans, outputs, datastore. Private forever.

Routing between the two is declared once in the engine's config/routing-map.yaml and resolved at runtime by the data-root seam in scripts/utils/workspace.py. Code never joins an engine root to a data directory — it calls helpers (get_data_root(), get_outputs_dir(), get_crm_contacts_dir(), get_knowledge_dir(), …) that all resolve under the data overlay. A guard test plus a pre-commit hook forbid the bypass, so new data always lands here, never in the engine clone.

Routing has three destinations: engine (code, public), private (operator-only data — this overlay's default for real data), and corporate (content shared down to a fleet of executives). The map default is engine, so code-ish paths fall through to shareable; every real-data directory carries an explicit private rule to fail closed.

Annotated directory tree

.heading-os-data/
├── crm/                          # Personal CRM — relationship data (PRIVATE)
│   ├── contacts/                 #   one markdown file per contact: contacts/<contact>.md
│   ├── address-book/             #   lightweight contact directory (CORPORATE carve-out)
│   └── aggregated/               #   fleet-aggregated CRM rollups
│   #   config.md, aliases.md at root = CORPORATE carve-outs
│
├── knowledge/                    # Second brain / knowledge base (PRIVATE by default)
│   ├── odin-brain/               #   curated advisor brain (PRIVATE)
│   │   ├── principles/           #     distilled operating principles
│   │   ├── positions/            #     committed stances
│   │   ├── sources/              #     ingested source notes
│   │   ├── episodes/             #     logged "things that happened"
│   │   └── conflicts/            #     flagged contradictions
│   ├── shared/                   #   knowledge shared down to execs (CORPORATE)
│   └── technology/               #   technical notes
│
├── context/                      # Operator operating context (PRIVATE)
│   #   personal-info, business-info*, strategy*, people, pipeline, current-data
│   #   (* = CORPORATE carve-outs)
│
├── threads/                      # Operational thread registry — ongoing situations (PRIVATE)
│   ├── business/                 #   business threads: <date>-<slug>.md
│   └── archive/                  #   closed threads
│
├── plans/                        # Active implementation plans (PRIVATE)
│   └── archive/                  #   completed/superseded plans, by year
│
├── outputs/                      # EVERY generated artifact lands here (PRIVATE)
│   ├── deliverables/             #   finished documents (letters, proposals)
│   ├── documents/                #   rendered corporate docs by sender
│   ├── operations/               #   workspace state, dashboards, audits, handoffs
│   ├── intel/                    #   OSINT / intelligence briefs
│   ├── content/                  #   LinkedIn, social content drafts
│   ├── email-drafts/             #   outbound drafts awaiting approval
│   ├── _sync/                    #   calendar/comms sync artifacts (one file/day)
│   └── browser/, clipboard/      #   browser cache, captured clipboard images
│
├── datastore/                    # Source-of-truth original documents (CORPORATE by default)
│   ├── products/                 #   product materials (datasheets, decks)
│   ├── brand/                    #   design system: logos, fonts, templates, examples
│   ├── events/                   #   event contact DBs and schedules
│   ├── intelligence/             #   competitor/market intel (PRIVATE — operator-only)
│   └── investment/               #   investor decks + financials (PRIVATE — operator-only)
│
├── auto-memory/                  # Persistent file-backed memory (PRIVATE)
│   #   MEMORY.md = index; one file per durable memory
│
├── admin/                        # Fleet administration (PRIVATE — operator/admin only)
│   ├── provision/                #   exec-provisioning tooling + generated packets
│   #   executives.json = the fleet roster
│
├── reference/                    # Operator reference content (mostly PRIVATE)
│   #   workspace-overview, voice files, operating policy, market/strategy reference
│   #   (engine ships generic *.example.* templates for shareable ones)
│
├── config/                       # Per-instance config (PRIVATE)
│   #   real identity / rosters / topology; engine ships *.example.* counterparts
│
├── corporate/                    # Fleet-shared daemon/base config (CORPORATE)
│
├── docs/                         # Operator-internal docs (mostly PRIVATE)
│   ├── superpowers/              #   internal design/plan/spec archive
│   └── security/                 #   security posture / findings
│
├── templates/                    # Operator content templates (PRIVATE)
├── _archive/                     # Historical / retired content (PRIVATE)
│
└── .claude/                      # Per-machine runtime state (PRIVATE)
    └── projects/                 #   session transcripts (.jsonl)
    #   plus .memory-index/ (gitignored, rebuildable — never pushed)

Top-level directories

Directory	Purpose
`crm/`	Personal CRM. `contacts/` holds one file per relationship; `address-book/`, `config.md`, `aliases.md` are lighter shareable directory/config.
`knowledge/`	The second brain. `odin-brain/` is the curated advisor brain; `shared/` is fleet-shareable.
`context/`	The operator's operating context: who they are, the business, strategy, key people, pipeline, current metrics.
`threads/`	Operational registry of ongoing situations, opened / logged / closed as work in flight.
`plans/`	Active implementation plans; completed plans move to `archive/`, never deleted.
`outputs/`	Every artifact the assistant generates — the single sink for generated work, organized by type.
`datastore/`	Authoritative original documents (PDFs, decks, contracts) used as source-of-truth for factual claims.
`auto-memory/`	Persistent cross-session memory: the `MEMORY.md` index plus one file per durable observation.
`admin/`	Fleet administration: the executive roster, provisioning tooling, admin guides.
`reference/`	Operator reference content: workspace catalogue, voice files, operating rhythm, market/strategy reference.
`config/`	Per-instance configuration carrying real identity, rosters, and topology (the engine ships `.example.` stand-ins).
`corporate/`	Base daemon/config content shared down to an executive fleet.
`docs/`	Operator-internal documentation: design/spec archive and security posture.

Privacy classification

Per the engine's classification rule, every path resolves to one of three routing destinations:

PRIVATE (operator-only — never shared): crm/contacts/, knowledge/ (incl. odin-brain/), context/, threads/, plans/, outputs/, auto-memory/, admin/, templates/, _archive/; docs/superpowers/, docs/security/; config/ and most of reference/; within datastore, intelligence/ and investment/.
CORPORATE (shared down to a fleet, not public): corporate/, datastore/ (general default), knowledge/shared/, and named carve-outs (context/business-info.md, context/strategy.md, crm/config.md, crm/aliases.md, crm/address-book/).
ENGINE (code, public): lives in the other repo (.heading-os), not this overlay. The routing default of engine means anything unmatched is treated as shareable code — which is exactly why every real-data directory above carries an explicit private rule, so operator data fails closed rather than leaking into the public engine.