Every DKS vault divides its workspace into three spaces: **agent** (`util/ai/`), **knowledge**, and **ops**. This is not an organizational preference but an architectural decision driven by failure mode prevention. The three spaces have fundamentally different durability profiles, growth patterns, and query characteristics. Conflating any two produces predictable, documented failures. --- ## Folder Structure ```sh vault-root/ ├── +inbox/ # Capture and staging (throughput, not storage) ├── calendar/ # Logs and Events (the one folder with intentional subfolders) │ ├── logs/ # Daily and weekly notes (date-named: 2026-03-19.md, 2026-W12.md) │ └── events/ # Meetings, trips, conferences (descriptive-named: rails-conf-2026.md) ├── resources/ # Sources, prompts, software, and general reference pages ├── notes/ # Atomic knowledge claims ├── projects/ # Bounded efforts with goals and timelines ├── domains/ # Long-lived areas of responsibility (Ruby, DevOps, Health, Finance) ├── systems/ # Systems and infrastructure you own or operate ├── archives/ # One-way graveyard for anything no longer useful ├── ops/ # Operational coordination │ ├── goals.md # active when util/ai/ is disabled │ ├── reminders.md │ ├── methodology/ # active when util/ai/ is disabled │ ├── sessions/ │ ├── health/ │ ├── observations/ │ └── queue/ └── util/ # Vault infrastructure (not domain knowledge) ├── ai/ # Agent identity and orientation (optional) │ ├── identity.md │ ├── methodology.md │ ├── goals.md │ ├── relationships.md # optional │ └── memory/ # optional ├── scripts/ └── templates/ ``` ### Design Principles **Type is frontmatter, not folder path.** Folders are storage. Obsidian Bases and the CLI are the query and creation layers. The `type` frontmatter field is what distinguishes object kinds — not where they live on disk. This keeps the root flat, enables type-scoped queries without folder traversal, and means the vault remains legible outside Obsidian (in Git, the CLI, a file browser). **Folders are flat except where workflow demands otherwise.** `calendar/` is the one justified exception — `logs/` and `events/` have different naming conventions (date-named vs. descriptive) that would create visual noise in a flat folder. All other folders are flat. **Ten root folders. No more without a structural reason.** --- ## Object Types DKS defines typed object categories. Type is declared in frontmatter and drives schema, not folder location. | Type | Default Folder | Purpose | | ---------- | ------------------ | -------------------------------------------------------------------------------------------- | | `log` | `calendar/logs/` | Daily and weekly notes — time-indexed records of how you spent your time | | `event` | `calendar/events/` | Meetings, trips, conferences — MOC-style, accumulates links over time | | `page` | `resources/` | Default type for general reference material, ADRs, and anything without a more specific type | | `prompt` | `resources/` | Reusable LLM prompts and prompt patterns | | `software` | `resources/` | Tools, libraries, packages, applications | | `source` | `resources/` | External inputs — articles, books, talks, papers | | `note` | `notes/` | Atomic knowledge claims | | `project` | `projects/` | Bounded efforts with goals and timelines | | `domain` | `domains/` | Long-lived areas of responsibility (Ruby, DevOps, Health, Finance) | | `system` | `systems/` | Systems and infrastructure you own or operate | ### Tag Conventions Tags follow a namespaced format: `["type/adr", "topic/dks", "topic/architecture"]`. Tag vocabulary is fixed at vault init — tags are not invented at capture time. This prevents fragmentation and enforces convention through structure rather than discipline. ### Frontmatter Conventions - **Title** is the filename, not a frontmatter field - **Required fields** for all objects: `type`, `tags`, `date` (where applicable) - **Type-specific fields** vary per object type (e.g. `period: daily` for logs, `event_type: conference` for events) --- ## +inbox/ — Capture and Staging **Durability:** Throughput. Nothing in `+inbox/` is permanent. **Purpose:** `+inbox/` is the entry point to the knowledge graph — the place where untyped, unprocessed material stages before becoming a typed object. It is not operational coordination (`ops/`) and not a knowledge store. It is pre-knowledge. ### Two Capture Targets DKS has two capture surfaces with different characters: | Surface | Location | Character | | ---------- | ---------------- | ------------------------------------------------------------ | | Daily note | `calendar/logs/` | Contextual capture — bullets tied to what you were doing | | Inbox | `+inbox/` | Decontextual capture — unprocessed notes, no frontmatter yet | The typical flow: items captured as bullets in a daily note get pulled out into `+inbox/` as standalone notes, then promoted to typed objects once their type and value is clear. ### Promotion Rules ```sh +inbox/ → notes/ (becomes a typed knowledge claim) → resources/ (becomes a source, prompt, software object, or page) → archives/ (captured but not worth keeping as a live object) ``` `+inbox/` can route directly to `archives/` for material that was captured but on reflection has no lasting value. Processed notes move out; `+inbox/` stays empty-ish. --- ## Knowledge Space — notes/, resources/, projects/, systems/, calendar/ **Durability:** Permanent. Everything here should be worth finding again. **Growth pattern:** Steady — proportional to active project and research throughput. **Load pattern:** Progressive disclosure. Too large to load fully. Use tag queries, Bases views, and link traversal to find relevant content. **Purpose:** The reason DKS exists. The developer’s intellectual workspace where knowledge compounds through typed object connections. ### domains/ — Areas of Responsibility `domains/` holds a small, fixed set of MOC hub files — one per long-lived area of responsibility. These are analogous to Areas in the PARA method: they have no end date and persist as long as that area of your life is active. **Domain files are sparse by design.** The folder contains a handful of files that rarely change, not a growing collection. Each domain file (`@work.md`, `@remote-ruby.md`, etc.) contains embedded Obsidian Bases queries that dynamically aggregate all objects tagged with that domain, plus any small inline notes. **The `@` prefix** is a UX affordance for Obsidian’s wikilink combobox — typing `@` in a link surfaces domain files immediately. It is not structural metadata. **Domain vocabulary (fixed):** | Tag | Area | | -------------------- | ----------------------------- | | `domain/work` | Day job | | `domain/remote-ruby` | Podcast hosting | | `domain/personal` | Non-work projects | | `domain/finance` | Financial management | | `domain/home` | Home ownership and management | | `domain/travel` | Travel planning and trips | **Objects declare domain membership via tags, not folder location.** A Linear issue becomes `type: project, subtype: task` with `tags: ["domain/work"]`. A podcast planning project gets `tags: ["domain/remote-ruby"]`. The domain file aggregates them via Bases — no manual linking required. **Multi-domain tagging is allowed** where genuine overlap exists. A conference trip might be `domain/travel` and `domain/remote-ruby`. A home office expense might be `domain/home` and `domain/finance`. This should reflect real overlap, not substitute for picking the right primary domain. ### calendar/ — Logs and Events **Logs** (`calendar/logs/`) are self-contained time-stamped records. Daily notes track how you spent your time, capture thoughts and ideas in bullet lists, and link to meetings, projects, and notes created. Weekly notes summarize the daily notes from that week for easy review. Logs are durable by nature — they’re a permanent time-indexed record. **Events** (`calendar/events/`) are MOC-style objects that accumulate links over time. They start sparse and grow as the event unfolds: - _Meeting workflow:_ pair with coworker on Linear issue → record and summarize in Spark Mail → create meeting note → copy summary and action items → link to project - _Conference workflow:_ project for planning → event note when dates finalized → update event note during conference to link to notes created (functions as a MOC) - _Trip workflow:_ project for planning → event note for tracking → add notes and observations to event note during trip ### resources/ — Sources, Prompts, Software, Pages `resources/` is a mixed-type folder. Type is differentiated by frontmatter. It holds: - **Sources** — external inputs processed via the CODE workflow (Capture → Organize → Distill → Express). When a source is distilled, notes or resources that reference it link back to it in the markdown body (not frontmatter). Sources stay in `resources/` as long as they’re useful as reference; they move to `archives/` when no longer relevant. Short-lived sources (e.g. a code snippet save) can skip distillation and go straight to `archives/`. - **Prompts** — reusable LLM prompts and patterns - **Software** — tools, libraries, packages, applications - **Pages** (default type) — general reference material, ADRs, anything without a more specific type ### Schema Evolution — ADRs Significant DKS schema and structure decisions are recorded as Architecture Decision Records (ADRs) in `resources/`. Git handles what changed; ADRs handle why. **ADR frontmatter:** ```yaml --- type: adr up: - "[[Project|System|Domain]]" tags: ["topic/dks", "topic/architecture"] created_on: 2026-03-19 --- ``` Title is the filename (e.g. `ADR20260319-frontmatter-over-folders.md`). One ADR per significant decision. Body follows a lightweight Context / Decision / Consequences format. ### Design Rule **Typed, composable, worth finding again.** If it won’t be queried or linked, it doesn’t belong here. Raw capture starts in `+inbox/` and gets processed into typed objects. Session-specific observations start in `ops/` and get promoted when they earn permanence. ### What Does NOT Belong in the Knowledge Space - Processing queue state → `ops/queue/` - Operational session logs → `ops/sessions/` - Agent self-knowledge → `util/ai/` - Health reports → `ops/health/` - Unprocessed captures → `+inbox/` --- ## archives/ — The Graveyard **Durability:** Permanent but inactive. One-way move. **Purpose:** A flat resting place for anything no longer useful. Not a reference library — a graveyard. ### What Gets Archived | Source | Condition | | ------------------ | --------------------------------------------------------- | | `projects/` | Project completed | | `domains/` | Area of responsibility retired or consolidated | | `notes/` | Note superseded or no longer accurate | | `resources/` | Source outdated, software no longer used, prompt obsolete | | `systems/` | System decommissioned | | `calendar/events/` | Old events with no ongoing reference value | | `+inbox/` | Captured but not worth keeping as a live object | ### Rules - **Flat** — no subfolders - **Typed frontmatter preserved** — archived objects keep their `type` and `tags` fields. Bases can still query across archives if needed. - **One-way** — objects do not come back out of archives except in unusual circumstances --- ## Agent Space — Agent Identity and Orientation (Configurable) **Enforcement:** Configurable. Off by default for pure knowledge vaults, on by default for personal assistant vaults. **Durability:** Permanent. Content accumulates slowly and is rarely deleted. **Growth pattern:** Slow — tens of files, not hundreds. **Purpose:** The agent must remember who it is before doing anything else. Without `util/ai/`, every session starts from zero. ### When Agent Space Is Enabled | File | Contents | Update Trigger | | ------------------------ | ------------------------------------------------------------ | ------------------------------------- | | `util/ai/identity.md` | Who the agent is — personality, voice, approach, values | Rarely | | `util/ai/methodology.md` | How the agent works — DKS conventions, processing principles | When operational learnings accumulate | | `util/ai/goals.md` | Current threads — active, deferred, completed | Every session | Optional extensions: `util/ai/relationships.md`, `util/ai/memory/`. ### When Agent Space Is Disabled | Function | Fallback | | ------------------- | ------------------ | | Goals / orientation | `ops/goals.md` | | Methodology | `ops/methodology/` | | Identity | Context file | ### Design Rule **Only what the agent needs about itself.** `util/ai/` answers: _“Who am I? How do I work? What am I working on?”_ Domain knowledge lives in the knowledge space. Processing scaffolding lives in `ops/`. --- ## Ops Space — Operational Coordination **Durability:** Temporal. Content flows through, gets processed, and either graduates to a typed object or gets archived. **Growth pattern:** Fluctuating — grows during active work, shrinks during maintenance. **Purpose:** Keep the knowledge graph clean by separating operational scaffolding from durable typed objects. ### Contents | Path | Contents | Lifecycle | | ------------------- | ------------------------------------------------------------------ | -------------------------------------------- | | `ops/goals.md` | Current threads — active when `util/ai/` is disabled | Active rotation | | `ops/reminders.md` | Time-bound actions, checked at session start | Active rotation | | `ops/sessions/` | Session logs, handoff notes | Rolling archive — 30+ day logs can be purged | | `ops/health/` | Schema validation, orphan objects, frontmatter violations | Superseding | | `ops/observations/` | Operational learnings — pre-promotion holding area | Graduating | | `ops/queue/` | Processing queue state | Flowing | | `ops/methodology/` | Vault configuration rationale — active when `util/ai/` is disabled | Semi-permanent | ### Reminders ```markdown # Reminders - [ ] 2026-03-25: Follow up on Linear ticket DKS-42 - [x] 2026-03-10: Migrate searchRegistry.js to QuickAdd (done 2026-03-10) ``` Checked at session start. Completed items marked and eventually archived. ### Content Promotion Rule Content moves from temporal to durable, never the reverse: ```sh ops/observations/ → notes/ (observation proves durable) ops/observations/ → util/ai/methodology.md (observation is about agent operation) ops/sessions/ → calendar/logs/ (session insight worth logging permanently) ``` --- ## Six Failure Modes of Conflation ### 1. Ops into Knowledge Processing queue state and session logs end up in typed object folders. Search returns processing debris alongside real objects. Tag queries surface operational entries that don’t belong. **Example:** A session log entry “processed 5 GitHub issues, found connection between X and Y” gets filed as a `note`. The connection is a note; the processing status is not. ### 2. Self into Knowledge Agent identity and methodology end up in the DKS object graph. Schema confusion — agent self-knowledge has different fields than typed DKS objects. The developer’s graph contains content about the agent rather than the domain. **Example:** “I work best when applying schemas in batches” filed alongside `software/` objects in `resources/`. ### 3. Knowledge into Ops Genuine insights stay trapped in session logs, never becoming typed objects. Knowledge is lost when `ops/` is archived. The vault appears thinner than the work invested would suggest. **Example:** “Sidekiq’s retry logic interacts with Rails autoloading in a specific way” captured in a session log, never promoted to a `note`, lost when the log is archived. ### 4. Self into Ops Agent identity scattered across session logs instead of curated in `util/ai/`. Orientation fails — the agent can’t reconstruct who it is from 50 session logs. Identity drifts because there’s no authoritative source. ### 5. Ops into Self Agent identity polluted with temporal processing state. `util/ai/` becomes too large to load fully at session start. The agent’s self-model includes current queue status as if it were identity. ### 6. Knowledge into Self Domain knowledge stored in `util/ai/` because it felt operationally relevant. `util/ai/` bloats. Search in typed folders misses content hidden in `util/ai/`. **Example:** “Rails favors convention over configuration” stored in `util/ai/memory/` instead of `notes/`. --- ## Content Routing Decision Tree ```sh Is this about the agent itself? ├── YES: Is it durable self-knowledge? │ ├── YES → util/ai/ (identity, methodology, goals, memory) │ └── NO → ops/ (session log, current processing state) │ └── NO: Is this developer/domain knowledge? ├── YES: Is it processed and typed? │ ├── YES → typed object folder (notes/, resources/, systems/, etc.) │ └── NO → +inbox/ (stage here, promote when type is clear) │ └── or ops/ if it's an operational observation │ └── NO: Is this operational coordination? └── YES → ops/ (queue state, health report, session handoff) ``` ### Quick Routing Rules | Content | Destination | Why | | -------------------------------- | ------------------------------------------------------------- | ------------------------------------------- | | Thought captured mid-flow | `calendar/logs/` bullet → `+inbox/` | Contextual capture, then stage | | Untyped note without frontmatter | `+inbox/` | Needs processing before it has a home | | Atomic knowledge claim | `notes/` | Durable, typed, worth finding again | | Article or book I processed | `resources/` (type: source) | External input, CODE workflow | | Tool or library I use | `resources/` (type: software) | Typed software object | | Reusable LLM prompt | `resources/` (type: prompt) | Typed prompt object | | DKS schema decision rationale | `resources/` (type: page, tags: type/adr) | ADR pattern | | Meeting or conference | `calendar/events/` | MOC-style event object | | Daily or weekly note | `calendar/logs/` | Time-indexed log | | Area of ongoing responsibility | `domains/` | Long-lived, no end date — MOC hub via Bases | | Linear issue / task | `projects/` (type: project, subtype: task, tags: domain/work) | Bounded, typed, domain-tagged | | Bounded effort with a goal | `projects/` | Typed project object | | System I own or operate | `systems/` | Typed system object | | Completed project | `archives/` | One-way move | | Captured but not worth keeping | `+inbox/` → `archives/` | Skip typed folders entirely | | Follow up by Friday | `ops/reminders.md` | Time-bound action | | Today’s processing log | `ops/sessions/` | Temporal processing state | --- ## Cross-Reference - **Failure modes beyond conflation:** Operational decay patterns (collector’s fallacy, orphan drift, schema erosion) are structural failures distinct from the conflation failures documented here. - **Schema definitions per object type:** See the DKS object model spec for full frontmatter schemas, required vs optional fields, and naming conventions per type. - **GitHub and Linear alignment:** `systems/` objects map to GitHub repos; `projects/` objects map to Linear projects. Ops state never lives in these typed folders. - **Bases and CLI:** Query and creation layers sit above folder structure. Type-scoped views, filtered bases, and CLI scaffolding all operate on frontmatter fields, not folder paths.