LifeOS
LifeOs

Life OS Schema

Last synced: Aug 14, 2026

Life OS Schema

⚠️ SUPERSEDED AS A LAYOUT SPEC — read this first

The layout described below is not what LifeOS installs. The installed layout is canonical: what install.sh lays down in LIFEOS/USER/, and what a running system reads. Where this document and the installed tree disagree, the installed tree wins. Do not rename anything to match this page. (public issue #1720, @catchingknives)

What is actually canonical:

  • ALL_CAPS names, not PascalCase. PRINCIPAL_IDENTITY.md, WRITINGSTYLE.md, PROJECTS.md — §2’s PascalCase rule was never adopted.
  • Domain directories sit at USER/ root: PRINCIPAL/, DIGITAL_ASSISTANT/, TELOS/, HEALTH/, FINANCES/, BUSINESS/, WORK/, SECURITY/, CONFIG/, CUSTOMIZATIONS/.
  • TELOS/ holds the goal files plus CURRENT_STATE/ and IDEAL_STATE/, each carrying its own domain files (HEALTH.md, INFRASTRUCTURE.md, FINANCIAL.md, …). Those are state snapshots and are distinct from the root HEALTH/ and FINANCES/ directories.
  • The operative frontmatter convention is pai-freshness-v1 (last_updated, last_updated_by, convention, last_reviewed, last_reviewed_by) — see LIFEOS/DOCUMENTATION/Freshness/FreshnessSystem.md. It is not the five-field category/kind/publish/review_cadence/last_updated contract in §3 below.

The body is kept as history: it records the shape that was designed in April 2026 and the reasoning behind it, and §4–§5 still describe how Pulse groups and renders files where those fields are present. Treat it as a design document, not as a spec to conform to.

The originally proposed shape of the USER directory in LifeOS.

Everything your DA knows about you lives in one flat, biography-style tree. This spec defines the rules every LifeOS user follows — so the same Pulse dashboard, the same Interview skill, the same Daemon aggregator, and the same skills work for everyone out of the box.

Status: Superseded as a layout spec · drafted 2026-04-16 · superseded 2026-08-07 Applies to: historical — for the live shape, read an installed LIFEOS/USER/ tree Companion docs: LIFEOS/DOCUMENTATION/LifeOs/LifeOsThesis.md (the why), LIFEOS/DOCUMENTATION/Pulse/PulseSystem.md (the dashboard), LIFEOS/DOCUMENTATION/Freshness/FreshnessSystem.md (the operative frontmatter convention), and the USER/ starter scaffold the LifeOS release skill ships at install/USER/

1. The One Rule

Single concept → single file at USER/ root. Multi-file concept → capitalized directory at root, with README.md as the narrative entry.

That is the whole organizing principle. No other nesting justification counts. If a concept can live in one file, it does, at root. If it genuinely needs many files (labs, customer folders, contract templates), it becomes a directory.

The USER/ root should read like a biography — not a filing cabinet. Walking into it should reveal the person, not the taxonomy.

2. Naming Convention

RuleExample
PascalCase, always. No underscores, no ALL_CAPS, no kebab-case.PrincipalIdentity.md, not PRINCIPAL_IDENTITY.md or principal-identity.md
Multi-word → single joined word, camel caps.WritingStyle.md, AssetManagement.md, CoreContent.md
Directories follow the same rule.Health/, Business/, Customizations/
Semantic names, not generic.Music.md (not Bands.md), Food.md (not FoodPreferences.md)

3. Frontmatter Contract

Every .md file in USER/ (root files and files inside directories) carries YAML frontmatter. This is the API between the file and every consumer (Pulse, Daemon, Interview, skills).

---
category: taste                # identity | voice | mind | taste | shape | ops | domain
kind: collection               # collection | narrative | reference | index
publish: daemon                # false | daemon-summary | daemon | public
review_cadence: 180d           # 30d | 90d | 180d | 365d | never
interview_phase: 3             # 1 | 2 | 3 | 4 — used by Interview skill
last_updated: 2026-04-16
---
FieldRequiredPurpose
categoryyesPulse grouping. Determines dashboard section.
kindyesRender contract. Picks which Pulse component displays the file.
publishyesDaemon broadcast flag. Default false.
review_cadenceyesStaleness timer. Pulse/Interview surface re-review when exceeded.
interview_phasenoInterview skill ordering. Omit = auto-detect from category.
last_updatedyesISO date. Maintained by writer (human or DA).

4. Categories (the 7)

Root files are grouped by category:. The first six are single-file concepts; the seventh is multi-file domains (directories).

CategoryMeaningExample files
identityWho you are — the irreducible “this is me”PrincipalIdentity.md, DaIdentity.md, OurStory.md, Opinions.md, Resume.md, Contacts.md
voiceHow you communicateWritingStyle.md, RhetoricalStyle.md, DaWritingStyle.md, AiWritingPatterns.md, Pronunciations.md
mindHow you thinkBeliefs.md, Wisdom.md, Models.md, Frames.md, Narratives.md, Definitions.md, Ideas.md, Learned.md, Wrong.md
tasteWhat you loveBooks.md, Authors.md, Movies.md, Music.md, Artists.md, Restaurants.md, Food.md, Podcasts.md, Coffee.md
shapeHow your life runsRhythms.md, Sparks.md, Creative.md, Civic.md, Meetups.md, Predictions.md, Traumas.md, Current.md, Ideal.md
opsInfrastructure of selfProductivity.md, AssetManagement.md, Feed.md, Architecture.md
domainMulti-file life domains (directories)Telos/, Health/, Finances/, Business/, Work/, Relationships/, Security/, Daemon/

Users may define their own category values. Pulse auto-groups by category string; adding category: travel creates a new section.

5. Kinds (the 4 Render Contracts)

Pulse has one React component per kind:. Four components render the entire USER/ tree.

kind:RendererWhat the file contains
collection<CollectionView> — sortable list, item cardsEnumerated items with optional ratings/notes. Books.md, Movies.md, Music.md, Restaurants.md, Podcasts.md, Meetups.md
narrative<NarrativeView> — prose card, section nav, pull-quotesEssays, beliefs, story-shaped content. Beliefs.md, Wisdom.md, OurStory.md, Rhythms.md, WritingStyle.md
reference<ReferenceView> — key/value table, monospaceLookup tables, definitions, mappings. Contacts.md, Pronunciations.md, Definitions.md, Architecture.md
index<IndexView> — tile grid linking to childrenDirectory entry points. Health/README.md, Business/README.md, Telos/README.md

6. Collection Item Format

Every file with kind: collection uses the same human-readable item shape. Markdown list, one item per line:

- **{name}** — {creator} · ★{rating} · {notes}

All parts after name are optional. The parser is permissive — anything not matching becomes notes. Examples:

- **Meditations** — Marcus Aurelius · ★10 · stoic operating system
- **Antifragile** — Taleb · ★9 · systems that gain from disorder
- **Deep Work** — Newport · ★8
- **Thinking, Fast and Slow** — Kahneman
- **Shōgun** — James Clavell

No schema file needed. No registration. Drop the file, Pulse parses it.

7. The Publish Model (Daemon Broadcast)

The publish: frontmatter field is the universal broadcast contract. DaemonAggregator.ts scans USER/ and publishes anything above false.

ValueBehavior
falseStays private. Never leaves the machine. Default.
daemon-summaryDaemon gets count + last-updated only. “Currently reading 3 books” — no titles.
daemonFull file content published to daemon.{yourdomain}.com.
publicPublished to daemon AND exposed via LifeOS public API (for DA-to-DA protocols).

Per-item override: Inside a kind: collection file, prefix an item with (private) to exclude it from publish even when the file is publish: daemon:

- **The Dark Forest** — Liu Cixin · ★9
- (private) **Some embarrassing book** — Author · ★3

Classification inheritance: Files inside a domain directory inherit the directory README’s publish: unless they set their own. Always private by default for domain files (health, finances, work, business).

8. Directory Anatomy (Multi-File Domains)

When a concept genuinely needs many files, it becomes a capitalized directory at USER/ root. The shape inside is:

Health/
  README.md        # kind: index — narrative entry, links to children
  Metrics.md       # kind: collection or reference
  Providers.md     # kind: reference
  Medications.md   # kind: collection
  Conditions.md    # kind: narrative
  Fitness.md       # kind: narrative
  Nutrition.md     # kind: narrative
  Labs/            # subdirectory for time-series artifacts
    2026-01.md
    2025-09.md

Rules inside a directory:

  • README.md is always kind: index
  • One more level of nesting is permitted (Labs/ inside Health/) for time-series or per-entity isolation (customer folders inside Work/Customers/)
  • No deeper nesting without explicit justification in the domain README

9. Pulse Render Contract

Pulse reads Pulse/state/user-index.json — a typed JSON produced by Pulse/modules/user-index.ts. The indexer:

  1. Walks USER/ — root files (non-recursive) + one-level into each directory
  2. Parses frontmatter + body for each .md
  3. Computes derived fields (completeness, staleness_days, overdue_review, item_count, preview)
  4. Writes index
  5. Watches USER/ via fs.watch — re-parses changed files and broadcasts SSE user.file.updated events

Pulse routes:

/life                   — biography overview, all categories
/life/c/:category       — category filter (taste, mind, …)
/life/:filename         — single root file drilldown
/<domain>               — directory page (/health, /finances, /business, /work, /relationships, /telos, /daemon, /security)
/interview              — interview gaps + launcher

Routing is data-driven. New files and new categories appear automatically; no code changes.

10. Daemon Integration

DaemonAggregator.ts replaces its hardcoded file list with a scan:

// Every file with publish != "false" becomes a daemon entry
const entries = userIndex.publish_feed;
const daemonData = {
  entries: entries.map(e => ({
    title: e.title,
    category: e.category,
    kind: e.kind,
    publish: e.publish,
    content: e.publish === "daemon-summary" ? summary(e) : full(e),
    items: e.kind === "collection" ? e.items : null,
    last_updated: e.last_updated,
  })),
};
writeFileSync("daemon-data.json", JSON.stringify(daemonData));

No per-file selector logic. Frontmatter IS the contract.

11. Interview Integration

InterviewScan.ts reads user-index.json instead of scanning files directly. Each file’s interview_phase (or auto-derived from category) places it in the ordering:

PhaseTarget files
P1 — Foundational TELOSTelos/Mission.md, Telos/Goals.md, Telos/Problems.md, Telos/Strategies.md, Telos/Challenges.md
P2 — Ideal state dimensionsIdeal.md, Current.md, Rhythms.md, Sparks.md, plus domain Ideals
P3 — Taste and preferencesAll category: taste files (Books.md, Movies.md, Music.md, Restaurants.md, Food.md, …)
P4 — Identity, voice, mindAll `category: identity

Adding a new file with interview_phase: 3 auto-includes it in the P3 conversation.

12. Extension — How Users Add New Concepts

The extension contract, in full:

  1. Drop a new .md file at USER/ root with valid frontmatter. That’s it.
  2. Pulse’s fs.watch detects the new file → indexer parses it → dashboard renders a new tile.
  3. Daemon’s aggregator picks it up if publish: is set.
  4. Interview’s scan picks it up on next run.

Examples of user extensions:

USER/Podcasts.md          # new taste file
USER/Gratitude.md         # new mind file
USER/Travel.md            # new shape file with category: travel (novel category — auto-grouped)
USER/BoardGames.md        # new taste file

Zero code changes required in Pulse, Daemon, or Interview for any extension.

13. Forbidden Patterns

Don’tWhy
Nest preferences inside Preferences/ wrapperSingle-concept files belong at root, not grouped
Put time-series files at USER/ root (lab_results_Jan2026.md)Goes inside the domain directory under a time-series subdir (Health/Labs/)
Mix content-kind on a single fileOne kind: per file. Split instead.
Edit PrincipalTelos.md or other auto-generated filesMarked with generated: true in frontmatter. Write to sources; the generator rebuilds.
Use publish: true / publish: yesUse the enum values (`false

14. Public Release Story

  • Private content lives in USER/. Never committed to the public LifeOS repo.
  • Templates live in the release templates’ USER/ scaffold. Shipped with every LifeOS release. This is the scaffold a new LifeOS user starts with.
  • This spec (LifeOs/LifeOsSchema.md) is the contract. Public. Referenced by templates, Pulse renderer docs, Interview prompts.
  • ShadowRelease.ts never reads USER/. It reads the release templates’ USER/ scaffold + this spec.

New LifeOS user experience:

  1. Install LifeOS the platform-agnostic, AI-native way: hand the installer (skills/LifeOS/install/install.sh, or the install doc) to your own AI/harness, which installs the LifeOS/ skill and scaffolds USER/ from the release templates. No git clone into ~/.claude.
  2. Run Interview skill → conversation walks them through filling in files, phase by phase
  3. Pulse dashboard lights up as files gain content
  4. Daemon publishes nothing until the user sets publish: flags

15. File Inventory (Reference)

The canonical expected root file list for a fully-populated USER/. Not every user will have every file; the shape is reference.

USER/
  # identity
  PrincipalIdentity.md  DaIdentity.md  OurStory.md  Opinions.md  Resume.md  Contacts.md
  # voice
  WritingStyle.md  RhetoricalStyle.md  DaWritingStyle.md  AiWritingPatterns.md  Pronunciations.md
  # mind
  Beliefs.md  Wisdom.md  Models.md  Frames.md  Narratives.md  Definitions.md  CoreContent.md
  Ideas.md  Learned.md  Wrong.md
  # taste
  Books.md  Authors.md  Literature.md  Movies.md  Music.md  Artists.md
  Restaurants.md  Food.md  Podcasts.md  Coffee.md
  # shape
  Rhythms.md  Sparks.md  Creative.md  Civic.md  Meetups.md
  Predictions.md  Traumas.md  Current.md  Ideal.md
  # ops
  Productivity.md  AssetManagement.md  Feed.md  Architecture.md
  # domain directories
  Telos/  Health/  Finances/  Business/  Work/  Relationships/  Daemon/  Security/
  # infrastructure directories (system-operational, not life content)
  Config/  Credentials/  Customizations/  Terminal/  Workflows/
  Actions/  Flows/  Pipelines/  Arbol/  BrowserState/

16. Changelog

  • v1.0 (2026-04-16) — Initial draft. Companion to LifeOs/LifeOsThesis.md. Supersedes the ad-hoc USER/ structure.

Examples

One new file, and the whole system reacts

A user decides to track the board games they own. The schema makes this a thirty-second job.

  1. The One Rule picks the shape. Board games are a single concept, so it’s one file at root — BoardGames.md — not a Games/ folder and never a Preferences/ wrapper.

  2. Frontmatter is the whole contract. They set category: taste, kind: collection, publish: false, and add items in the standard line format:

    - **Terraforming Mars** — ★9 · long but worth it
- **Azul** — ★8 · fast, gorgeous tiles

  3. Everything else is automatic. Pulse’s fs.watch sees the new file, the indexer parses it, and a new tile appears under the taste section — rendered by <CollectionView> because kind: collection. The Interview skill folds it into its phase-3 taste conversation. The Daemon ignores it, because publish: false. No code was changed in Pulse, the Daemon, or Interview.

Later they flip publish: false to publish: daemon and the same file starts broadcasting to their public profile — same file, one field, new behavior. The frontmatter is the API.

When it’s one file, and when it’s a directory

The fork is legibility, not size of interest:

  • One concept → one root file. Board games, coffee, a list of beliefs — each is a single file that reads like a line in a biography.
  • A concept that genuinely needs many files → a directory with a README.md as its kind: index entry. A whole side business (contracts, customers, invoices) isn’t one file; it’s Business/. Health metrics plus lab time-series isn’t one file; it’s Health/ with a Labs/ subdir.

The test: could a stranger walk the root and see the person, not a filing cabinet? Single-concept files at root keep that true; premature folders break it.

flowchart TD
    F["BoardGames.md<br/>category + kind + publish"] --> I[Pulse indexer parses frontmatter]
    I --> P[New taste tile via CollectionView]
    I --> V[Interview: added to phase-3 taste]
    I --> D{publish flag}
    D -->|false| X[Stays private]
    D -->|daemon| B[Broadcast to public profile]

One file with valid frontmatter fans out to every consumer on its own. category picks the Pulse section, kind picks the renderer, publish decides broadcast — and none of it required touching code.