Proposal: model multiple entities, roles, and social circles (docs-only)

[grimmolf]

Summary

LifeOS is built around a single-entity assumption that the code states out loud: one principal with one company, one work repo, one flat TELOS, and one free-text Role:. Most real lives aren't shaped that way: a day job plus one or more side businesses, and identity spread across family, friends, and the groups we belong to (workplace, church, club, neighborhood).

This is a proposal-only PR. It adds one design document, LIFEOS/DOCUMENTATION/Proposals/MultiEntityLife.md, that specifies a generalization and asks for review of the model before any code phase lands. It changes no runtime behavior.

The problem, in the code

• resolveCompanyDir() picks one YOUR_COMPANIES/* dir and its own comment says it "works for exactly one person" (PULSE/Observability/observability.ts:2914-2920); /api/life/business takes no entity parameter (:4578).
• The Work System binds every stream of work to one GitHub repo (hooks/lib/work-config.ts:65-83, WorkConfig.repo: string | null), while a second path already loops config.repos (plural) — the plural shape exists, inconsistently.
• TELOS.md ingests per-business TELOS documents and discards which business each goal belongs to; GenerateTelosSummary.ts parses flat ID lists with no grouping key; LIFEOS_STATE.json has seven fixed dimensions and no per-entity split.
• Finances know many payers but tag expenses only as business | personal | mixed (observability.ts:1768-1789, normalized at 2655/2681), so several businesses collapse into one word.
• PRINCIPAL_IDENTITY.md has one Role: slot for what is, in practice, several roles across several organizations.
• The Life page has exactly one Business card and one Work card, singular at the type level (src/app/life/page.tsx:355-403, :78-95).

The proposal

Three primitives, threaded through existing surfaces as a data-model change, not an agent-topology change (LifeOS already tried per-entity agents and retired them; that decision stands):

• Entity — an organization you belong to (employer, business, nonprofit, club, church, neighborhood), in a new USER/ENTITIES.yaml registry.
• Role — your relationship to it: employee | owner | partner | member | volunteer | support.
• Circle — the social layer relative to you. 0 = family, 1 = friends, 2 = social-contract groups, 3 = everyone else, each with proportional diligence and a hard information boundary. Circle 2 is the entity layer, which is what unifies "multiple businesses + a job + social groups" into one model.

It also disentangles a word that is currently used for three different axes (agent identity layers, social diligence tiers, and TELOS activity priorities) into Layer / Circle / Priority.

The document ranks eight chokepoints by leverage, names existing code and conventions to reuse rather than duplicate (the Telos skill's Project-TELOS analyzer, the YOUR_COMPANIES/<name>/ and WORK/<customer>/ directory conventions, the Property: label taxonomy, the income_source.payer multi-source model), and lays out four independently shippable, non-breaking phases where a one-entity install behaves byte-for-byte as it does today.

Testing evidence

Docs-only; no runtime change. Every file:line citation was verified against upstream main at this commit: the ten cited anchors (BUSINESS_DIR, VendorYaml, ObligationYaml, handleLifeFinances, both scope normalizations, resolveCompanyDir, handleLifeBusiness, handleLifeWork, the /api/life/business route) match line-for-line, and the shipped observability.ts is byte-identical to upstream (blob 787cf286). Example data in the registry snippet is synthetic.

Requesting review on

1. Whether USER/ENTITIES.yaml should live in USER/ (private, per-install) with a shipped template.
2. Whether Circle is acceptable as the canonical social word (freeing "Tier" for the TELOS priority stack), or whether to keep "Tier" and rename only the priorities.
3. Whether role should be an enum or free text with a suggested vocabulary.

If the model is accepted, Phase 1 (registry + frontmatter contract, no behavior change) follows as a separate PR.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01DGcHcnVs5smQ7NCihbvasf

[danielmiessler]

Closing this as a PR and pointing it at Discussions. DOCUMENTATION/ ships in every release and mirrors to the public docs site, so a proposal there publishes as product doc. And multi-entity modeling is Vector's job in this system; core LifeOS models one principal. Happy to argue that in a Discussion thread.