Knowledge management folder conventions

Knowledge-Management Folder Conventions — Research

Target use case: ONE canonical folder layout used across (a) Obsidian vault containing business + agent doctrine + classified session archives, (b) per-agent variant runtime folders, (c) per-project code repos under ~/Work. Audience: solo operator running a 5-machine AI fleet on top of a client services business.

Date: 2026-05-11 Author: research subagent (Mac) Output target: /Users/wesleyhines/Work/tools/clean-desk-extract/research/sdk-patterns/03-knowledge-management.md

TL;DR Verdict (read this first)

Rank-ordered recommendation for Wes’s hybrid case:

**Lightly-numbered PARA top level + Johnny.Decimal inside structured zones
- LYT-style MOCs in the linking surface + flat atomic notes inside workpads.** This is the only configuration that survives all three target surfaces (vault, agent runtime, repo) without forcing one to wear a costume.
Pure PARA. Cleanest mental model, but breaks for agent runtime (variants are not “projects” — they’re long-lived processes) and breaks for repos (no apps/, packages/, tests/).
Pure Johnny.Decimal. Best when the artifact set is fixed and you never grep by intent. Worst when the artifact set evolves and 60% of the contents are agent context the LLM has to read — numbers in folder names confuse retrieval and waste tokens.
Pure Zettelkasten / LYT. Excellent for the notes surface but produces zero structure for repos or runtime folders. Disqualified as a unifier.
CODE method. Not a folder layout — it’s a workflow. Use it as the verb layer over whatever folder structure you pick.

Anti-pattern shortlist (every retrospective agrees on these):

Pre-creating empty folders “in case” — they rot and clutter the graph.
Numbering everything when 80% of content doesn’t need positional ordering.
Deep nesting (>3 levels) — kills CLI tab-completion and confuses both you and LLM agents.
Inconsistent naming (projects/ here, Projects/ there, 01_projects/ elsewhere) — every grep becomes guesswork.
Mixing taxonomy and time in the same level (e.g. 2026-projects/ next to clients/).

Detail and reasoning below.

1. PARA — Tiago Forte

What it is. Four top-level buckets organized by actionability, not topic:

Projects — short-term effort, specific outcome, deadline.
Areas — ongoing responsibilities you maintain indefinitely (Health, Finances, “Hines Creative ops”).
Resources — topic-of-interest reference material with no current action attached.
Archives — anything inactive from the other three. One-way trip.

The defining rule: organize by when you need it / what action it serves, not by what it’s about. A note titled “Tax Laws” goes inside Projects/ 2026 Tax Return/, not inside a Resources/Taxes/ folder, because that’s where you’ll actually open it. (fortelabs.com/blog/para/, mattgiaro.com/para-obsidian/)

Who uses it. Tiago Forte’s BASB students (>50k), the Obsibrain plugin, LifeOS template authors, most “Build a Second Brain” YouTubers. The canonical Obsidian PARA Starter Kit is the most-downloaded knowledge- management vault on the forum. (forum.obsidian.md/t/para-starter-kit/223)

When it works well.

Mixed personal + professional vaults where the same person owns everything.
Heavy project churn — you finish 5-10 projects a quarter and want them out of sight.
Pairing with Daily Notes / journaling — Areas hold the ongoing routines, Projects hold the active sprints.

When it breaks.

Folder-only thinking. Files live in one folder, so a single artifact belonging to two projects forces a choice. Obsidian’s strength is linking, not folder hierarchy — PARA forces choices that links would obviate. (brandonkboswell.com/blog/Should-you-use-PARA-in-Obsidian)
Project/Area boundary is fuzzy. “Marketing for Shaw” — is that a project (Q2 campaign) or an area (forever ongoing)? The thread forum.obsidian.md/t/22279 calls this out explicitly: “If a project has no goal, it’s just a hobby.”
Scale ceiling. One user at >1000 tasks across 10k notes reported feeling lost; PARA doesn’t enforce internal structure inside each Projects/<name>/ folder.
Bad for agent runtime. Variants are not projects. Forcing Pepper into Projects/Pepper/ is a category error — Pepper is an ongoing entity.

Tree (PARA applied to Wes’s hybrid case):

jarvis/hinesipedia/
├── 1-Projects/
│   ├── Shaw-Site-V4/
│   ├── Covenant-HCP-Sync-Phase-2/
│   ├── Summit-Q2-Meta-Campaign/
│   └── Clean-Desk-Extract/
├── 2-Areas/
│   ├── Hines-Creative-Ops/
│   ├── Fleet-Operations/
│   │   ├── doctrine/             # ethos, source-order, conventions
│   │   ├── protocols/            # handoff, compaction, fast-gate
│   │   └── variants/             # per-variant persona files
│   ├── Finances/
│   ├── Health/
│   └── Personal/
├── 3-Resources/
│   ├── design-systems/
│   ├── api-references/
│   ├── prompt-engineering/
│   └── ad-copy-swipefile/
└── 4-Archives/
    ├── projects-archive/
    ├── sessions-archive/         # the new classified session-archive tree
    │   ├── 2026/05/
    │   └── 2026/04/
    └── deprecated-doctrine/

Note: in this layout, agent variant doctrine lives under Areas, not Projects — because variants don’t finish. Session archives go in Archives (time-shifted, read-only). That’s the natural fit but it forces “Projects” to mean “buildable client work” only.

2. Johnny.Decimal — Johnny Noble

What it is. Hierarchical decimal numbering. Exactly 10 areas, each with exactly 10 categories, each holding up to 100 IDs.

Areas: 10-19, 20-29, … up to 90-99
Categories inside an area: e.g. 11, 12, 13 inside 10-19
IDs inside a category: 11.01, 11.02, …

So 13.07 is unambiguous: area 10-19, category 13, item 07. Every artifact gets a JD number. The number is the address. You can find anything by saying its number aloud. (johnnydecimal.com/10-19-concepts/11-core/11.02-areas-and-categories/, rknight.me/blog/using-the-johnny-decimal-system/)

For multi-domain setups, JD uses a system identifier prefix: S1.13.07 means System 1, area 10-19, category 13, item 07. Wes could have S1 (vault), S2 (Work repos), S3 (fleet runtime). (johnnydecimal.com/.../13.01-introduction/)

Who uses it. People with strong filing-cabinet instincts and lots of heterogeneous artifacts — lawyers, government workers, people running mixed-platform document piles (Drive + Dropbox + Obsidian + email). Hacker News thread 36308366 is mostly converts.

When it works well.

Fixed taxonomies that don’t churn. JD assumes you can pick your 10 areas once and live with them.
Cross-platform addressability — same JD number across Drive, Notion, Obsidian, finder. (lucaf.eu/2023/02/23/luca-decimal.html)
Speaking aloud / dictating (“send me 22.04”).
Physical + digital parity (filing cabinet labels).

When it breaks.

Premature taxonomy lock-in. Pick wrong, and the whole numbering shifts. Renumbering 200 items because you realized “Fleet” needed its own area is a real cost.
LLM token waste. Every path becomes 30-39 Fleet/33 Variants/33.04 Pepper/... — agents reading that pay 4x the tokens vs. fleet/variants/ pepper/.
Reservation waste. The decimal system reserves 10,000 possible locations; most stay empty forever. Critique noted at dsebastien.net/2022-04-29-johnny-decimal/.
Time burned refining numbers instead of doing work. Documented anti- pattern in the Medium piece by Cody Burleson (medium.com/@cody.burleson/ patterns-for-pkm-johnny-decimal-system-5753774e77fd).
Bad for repos. No npm/cargo/bun tool reads JD-prefixed paths naturally. You’d be the only one who knows what 33.04 means.

Tree (JD applied to Wes’s hybrid case):

jarvis/hinesipedia/
├── 10-19 Business/
│   ├── 11 Clients/
│   │   ├── 11.01 Shaw-Plumbing/
│   │   ├── 11.02 Covenant-Wildlife/
│   │   ├── 11.03 Summit-Energy/
│   │   └── 11.04 Wellness-Oasis/
│   ├── 12 Hines-Creative-Internal/
│   ├── 13 Finances/
│   └── 14 Marketing-Assets/
├── 20-29 Fleet/
│   ├── 21 Doctrine/
│   │   ├── 21.01 ethos.md
│   │   ├── 21.02 source-order.md
│   │   └── 21.03 conventions.md
│   ├── 22 Protocols/
│   ├── 23 Variants/
│   │   ├── 23.01 pepper.md
│   │   ├── 23.02 stark.md
│   │   └── 23.03 nagatha.md
│   ├── 24 State/
│   └── 25 Machines/
├── 30-39 Knowledge/
│   ├── 31 References/
│   ├── 32 Swipe-Files/
│   └── 33 Research/
├── 40-49 Sessions/
│   └── 41 Session-Archives/
│       └── 41.01 2026-05/
├── 50-59 Personal/
└── 90-99 Archive/

Verdict for Wes: JD numbers are friction for a vault that agents read constantly. The address-stability benefit doesn’t outweigh the token cost and the rename pain. Useful as an internal convention inside a structured zone (e.g. inside Fleet/protocols/ you could number protocols 01-handoff.md, 02-compaction.md) but NOT as the top-level shape.

3. Zettelkasten — Niklas Luhmann (and his German “slip box”)

What it is. Atomic notes, one idea per note, densely interlinked. Originally a literal box of index cards numbered by Luhmann’s idiosyncratic “Folgezettel” scheme; the notes themselves carry the structure through links, not folders. Two note types:

Permanent notes (Hauptnotizen): your own ideas, rewritten in your own words.
Literature notes: condensed source material, with backlinks to the permanent notes that reference them.
(Modern addition) Fleeting notes: capture inbox, processed daily.

The output of Zettelkasten thinking is a graph, not a tree. (obsidian.rocks/getting-started-with-zettelkasten-in-obsidian/, bryanhogan.com/blog/obsidian-zettelkasten)

Who uses it. Academics, writers (Sönke Ahrens’s “How to Take Smart Notes” is the canonical English text), researchers, long-form thinkers. Zettelkasten forum (forum.zettelkasten.de) is the purist community.

When it works well.

Single-domain knowledge worker output. Writers, researchers, theorists.
When the product is synthesis — books, papers, articles.
When you have months/years to let connections accrete.

When it breaks.

Atomic discipline collapses under work pressure. Most knowledge workers don’t have the slack to rewrite every captured idea as an atomic permanent note. The Obsidian forum has multiple threads of people abandoning pure Zettelkasten because it became overhead. (forum.obsidian.md/t/debating-the-usefulness-of-atomic-notes/38077)
Useless for transactional data. Invoices, client deliverables, ad campaign performance dumps — none of that wants to be atomic.
Useless for runtime/repo folders. A code repo isn’t a slip-box.
“Obsidian leads to confusing Zettelkasten.” The Zettelkasten forum has a long-running argument that Obsidian’s UX seduces users into abandoning Luhmann’s discipline. (forum.zettelkasten.de/discussion/1745)

Pragmatic adaptation: Hybrid users put Zettel-style atomic notes only in their Resources/ or Notes/ zone, not in Projects/ or Areas/ where transactional artifacts dominate. (medium.com/obsidian-observer/ fusing-the-two-most-powerful-note-taking-systems-in-obsidian)

Tree (Zettelkasten applied to Wes’s case — minimal, mostly disqualified):

jarvis/hinesipedia/
├── 0-Inbox/                       # fleeting notes, unprocessed
├── 1-Permanent/                   # atomic, linked, one idea each
│   ├── 202605111400-meta-broad-match-burns-budget.md
│   ├── 202605111415-summit-cpl-target-50.md
│   └── ...
├── 2-Literature/                  # source-attached condensations
├── 3-Daily/                       # journal
└── 4-MOC/                         # maps of content (LYT bolt-on)

This doesn’t accommodate Clients/Shaw/invoices/ or Fleet/protocols/. Disqualified as a unifier, but the linking philosophy is keepable.

4. LYT (Linking Your Thinking) / Maps of Content — Nick Milo

What it is. A practice, not a folder taxonomy. LYT’s core artifact is the Map of Content (MOC) — a note that links to other notes on a topic, acting as an evolving hub. MOCs are not folders; they’re indexes written by hand or generated by Dataview. Notes can appear in many MOCs; folders can’t replicate that.

LYT also pushes “ACE” (Act, Connect, Express) and “Ideaverse” as starter vaults. The framework explicitly rejects rigid up-front taxonomy in favor of letting structure emerge from accumulated MOCs. (linkingyourthinking.com/, medium.com/@nickmilo22/reflecting-on-the-age- of-the-linked-note-ff13945d6af4)

Who uses it. Obsidian power users with 5k+ notes who got bitten by PARA’s “one folder only” constraint. Workshop alumni (~6-week paid program). Authors of large research vaults.

When it works well.

High-volume note workflow where the same note belongs to multiple conceptual buckets.
Vaults dominated by synthesis output (essays, research, evergreen notes).
When you’re comfortable letting structure emerge — no urge to “tidy” the folder tree.

When it breaks.

MOCs need maintenance. A stale MOC is worse than no MOC. Wes’s rotating workload means MOCs would go stale fast unless an agent maintains them.
Doesn’t address transactional data. Same Zettelkasten problem — invoices and HCP exports don’t want to be linked notes.
No native repo answer. LYT has no opinion about ~/Work/clients/.

Tree (LYT applied to Wes’s case):

jarvis/hinesipedia/
├── +Index.md                      # the home MOC
├── +Fleet-MOC.md                  # links to all fleet doctrine
├── +Clients-MOC.md                # links to all client work
├── +Variants-MOC.md
├── Atlas/                         # MOCs, structural notes
├── Calendar/                      # daily/weekly/monthly
├── Cards/                         # atomic notes (Zettel-style)
├── Sources/                       # references, books, articles
├── Spaces/                        # workspaces for projects
└── Archive/

The + prefix on MOCs is canonical LYT — it sorts them to the top of folder listings. Verdict for Wes: MOC practice is keepable, but the top-level vocabulary (Atlas/Cards/Sources/Spaces) is too abstract for business+agent hybrid.

5. CODE — Tiago Forte (workflow, not layout)

What it is. Four verbs that describe the lifecycle of a piece of captured information.

Capture: pull anything interesting into an inbox. Don’t filter.
Organize: file by actionability (this is where PARA enters).
Distill: progressive summarization — bold, then highlight, then written summary at the top of the note.
Express: produce output — articles, decks, client deliverables, ad copy.

CODE is the verb layer; PARA is the noun layer. They’re explicitly designed together. (fortelabs.com/blog/basboverview/)

Who uses it. Anyone reading “Building a Second Brain.”

When it works well.

Any folder structure benefits from CODE’s discipline. Specifically: Distill (progressive summarization) is the rare PKM advice that holds up across systems.
Pairs cleanly with daily notes + inbox processing.

When it breaks.

It’s a process, not a structure. Doesn’t tell you how to lay out a vault. You still need PARA / JD / LYT under it.

Implication for Wes: treat CODE as the verbs that operate on whatever folder layout you choose. Specifically, allocate:

An Inbox (capture stage) — flat folder, processed daily/weekly.
A Distill habit at the top of every long doc (TL;DR + key bullets).
An Express output target — usually Projects/<name>/deliverables/ or Work/clients/<client>/.

No separate tree needed.

6. PARA Plus Logs/Daily — common Obsidian extension

What it is. PARA augmented with a Daily/ (or 0-Daily/) folder and an Inbox/ folder, sometimes also Templates/ and Attachments/. The daily folder holds journal entries named YYYY-MM-DD.md, often populated by the Daily Notes core plugin or the Periodic Notes community plugin.

Standard sections in a daily note:

Top 3 tasks
Log / journal
Meetings
Brain dump
Tomorrow’s prep

(dannb.org/blog/2022/obsidian-daily-note-template/, obsidian.rocks/my-current-daily-note-in-obsidian/)

Who uses it. Almost every “PARA in Obsidian” tutorial after ~2023 adds daily notes. LifeOS, Obsibrain, the canonical PARA starter kit all do this.

When it works well.

Anyone with ADHD-shaped working memory loss between days. (Wes, explicitly.)
Catching transient context: “what did I figure out yesterday?”
Agent handoffs and morning-review skills key off daily notes naturally.

When it breaks.

If you don’t open it daily, it rots and produces guilt without value.
If you over-template (50-field YAML frontmatter), it becomes a chore.

Tree (PARA + Daily applied to Wes’s case):

jarvis/hinesipedia/
├── 0-Inbox/                       # CODE-Capture stage
├── 0-Daily/                       # journal, YYYY-MM-DD.md
├── 1-Projects/
├── 2-Areas/
│   └── Fleet/                     # variants, doctrine, protocols
├── 3-Resources/
├── 4-Archives/
│   └── Sessions/                  # classified session-archives
├── _Templates/
└── _Attachments/

_ prefix (or 0- numeric) sorts utility folders to the top or bottom deterministically. This is the closest off-the-shelf pattern to what Wes needs.

7. Power-user vault layouts in the wild

Surveyed: kepano, Nick Milo, the Sweet Setup, the Obsibrain template, the LifeOS template, Sebastian Witowski, Matt Giaro, the Excellent Physician.

Kepano (Steph Ango, Obsidian CEO) — bottom-up + flat

Top-level only:

.obsidian/
Attachments/
Categories/
Clippings/
Daily/
References/
Templates/
[root]                             # most personal notes live here

Key philosophy: “I avoid folders because many of my entries belong to more than one area of thought.” Most personal notes live in the vault root. Organization happens via a categories: frontmatter property + Obsidian Bases plugin. (stephango.com/vault, github.com/kepano/kepano-obsidian)

This is the maximally-flat end of the spectrum.

Nick Milo / LYT Ideaverse — MOC-centric

+Maps/
Calendar/
Cards/
Efforts/                            # active projects
Sources/                            # external references
Spaces/                             # workspaces
Extras/

LifeOS / Obsibrain — PARA + Daily + heavy plugins

01 Projects/
02 Areas/
03 Resources/
04 Archives/
05 Daily Notes/
06 Templates/
07 Attachments/

Sweet Setup / Sebastian Witowski — minimal

Notes/
Daily/
Templates/
Attachments/

Pattern observations across all of them

Almost everyone has Daily, Templates, Attachments as siblings of the real content. These are utility folders, not knowledge folders.
Power users with >10k notes trend toward flatter trees (kepano, Nick Milo). They rely on links, frontmatter, and Bases/Dataview, not folder depth.
Numbered prefixes (01, 02) are common but optional — used purely for sort order, not for JD-style addressing.
No power user uses Johnny.Decimal as their top-level shape. JD shows up inside zones where addressability matters (legal files, tax records), never as the vault skeleton.
Plugin reliance correlates with note volume. Dataview, Bases, Templater, Periodic Notes are universal at scale.

(stephango.com/vault, forum.obsidian.md/t/14-example-vaults-from-around- the-web/81788, obsidianmate.com/vaults, aitooldiscovery.com/guides/ obsidian-reddit)

8. Monorepo and codebase layout conventions (cross-domain inspiration)

Turborepo / Nx / pnpm workspaces

Canonical layout (2026 consensus):

my-monorepo/
├── apps/
│   ├── web/
│   ├── api/
│   └── docs/
├── packages/
│   ├── ui/
│   ├── config/
│   ├── tsconfig/
│   └── utils/
├── tools/                         # build scripts, codegen
├── package.json
├── pnpm-workspace.yaml
└── turbo.json

apps/ — deployable end-products (one per app).
packages/ — shared libraries, consumed by apps.
tools/ — local scripts, generators, codemods (sometimes named scripts/).
infra/ — Terraform / CDK / Pulumi (added in some setups).
docs/ — markdown documentation (or a docs app inside apps/).

(turborepo.dev/docs/crafting-your-repository/structuring-a-repository, pnpm.io/workspaces, nx.dev/blog/setup-a-monorepo-with-pnpm-workspaces)

Python (src-layout)

project/
├── src/
│   └── project/
├── tests/
├── docs/
├── scripts/
└── pyproject.toml

(packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/)

Domain-Driven Design — bounded contexts

DDD organizes by bounded context at the top level, then application/domain/infrastructure layers inside each context. The bounded-context-per-folder pattern is the universal DDD answer to “how do I keep concerns separated?”

src/
├── billing/                       # bounded context
│   ├── application/
│   ├── domain/
│   └── infrastructure/
├── inventory/
│   ├── application/
│   ├── domain/
│   └── infrastructure/
└── shared-kernel/

(martinfowler.com/bliki/BoundedContext.html, dev.to/stevescruz/ domain-driven-design-ddd-file-structure-4pja)

Key insight from DDD that applies to Wes’s case: the top-level should reflect the language of the domain, not technical concerns. Translated: top-level folders should say what something is (client, fleet, session), not what it’s built with (markdown, json, ts).

Solo dev / freelance multi-client convention

Most-cited solo dev pattern (Marc Ashwell, Dave Woods, freelancermap, DEV community):

~/Work/
├── clients/
│   ├── <client-name>/
│   │   ├── _admin/                # invoices, contracts, briefs
│   │   ├── _brand/                # logos, fonts, brand guide
│   │   ├── <project-name>/
│   │   │   ├── input/             # client-supplied
│   │   │   ├── wip/               # work in progress
│   │   │   ├── output/            # deliverables
│   │   │   └── repo/              # the actual git repo
│   │   └── ...
│   └── ...
├── tools/                         # internal tools, MCP servers
├── active-projects/               # non-client experiments
└── archive/                       # paid-and-done work

(marcashwell.medium.com/how-to-organize-your-client-folders, dave-woods.co.uk/project-folder-structure-for-a-web-designer/, freelancermap.com/blog/organising-files-as-a-freelancer/)

This is roughly what Wes’s ~/Work/ already looks like (~/Work/clients/covenant/, ~/Work/clients/shaw-plumbing/, ~/Work/tools/campaign-engine/). The pattern is durable; keep it.

AI agent runtime folder conventions (emerging)

This is less established than the others — most teams are still figuring it out. Two emerging patterns:

MindStudio / BusinessOS pattern (mindstudio.ai/blog/agentic-operating- system-file-structure-context):

business-os/
├── claude.md                      # global rules
├── shared-brand-context.md
├── context/
│   ├── audience.md
│   ├── voice.md
│   └── product.md
└── skills/
    └── <skill-name>/
        ├── skill.md
        ├── examples.md
        └── learnings.md

AGENTS.md pattern (ai-insider.io/ultimate-agents-md-guide):

agent/
├── AGENTS.md                      # operating manual
├── SOUL.md                        # identity, persona, tone
├── USER.md                        # context about the human
├── MEMORY.md                      # long-term memory
├── TOOLS.md                       # API config
├── TASKS.md                       # active task queue
├── HEARTBEAT.md                   # check-in cadence
└── memory/
    └── YYYY-MM-DD.md

Wes’s current fleet already uses an evolved version of #2 — per-variant folders with persona docs, MEMORY.md, hooks, etc. Keep the pattern, harden the naming.

9. The Hybrid Recommendation (ranked)

Recommendation #1 — PARA-flavored top level with Johnny.Decimal inside structured zones and LYT MOCs in the linking surface

This is what actually fits all three target surfaces. Ranking it #1 because:

The PARA verbs (Projects / Areas / Resources / Archives) map cleanly onto Wes’s mental model: client gigs are projects, fleet ops are areas, swipe-files are resources, classified session archives are archives.
Variants live in Areas/Fleet/variants/ — they’re ongoing, not finishable.
Session archives live in Archives/sessions/YYYY/MM/ — already time-naturally-sorted, no JD required.
JD-style numbering is allowed inside zones where stable addressability matters (e.g. protocol numbering: 21-handoff.md, 22-compaction.md) but doesn’t dominate the top level.
MOCs (+Fleet-MOC.md, +Clients-MOC.md) live in the vault root and cross-link everything. This recovers Obsidian’s graph strength without forcing folder duplicates.
The Work/ repo tree and per-agent runtime folders mirror the same PARA verbs with one substitution: instead of Projects/, repos use apps/ + packages/ + tools/ (industry standard) and agents use tasks/ + memory/ + handoffs/ (fleet convention).

Top-level shape (the unifier):

<root>/
├── 0-inbox/         # capture (CODE-Capture)
├── 0-daily/         # journal, only in vault
├── 1-projects/      # OR apps/ in repos, OR tasks/ in agent runtime
├── 2-areas/         # OR packages/ in repos, OR memory/ in agent runtime
├── 3-resources/     # OR docs/ in repos, OR reference/ in agent runtime
├── 4-archives/      # always present, always read-only
├── _templates/
├── _attachments/    # (vault only)
└── _meta/           # README, config, conventions

Then for each surface:

Vault (~/jarvis/hinesipedia/):

hinesipedia/
├── 0-inbox/                       # daily capture, weekly process
├── 0-daily/
│   └── 2026/05/2026-05-11.md
├── 1-projects/
│   ├── shaw-site-v4/
│   ├── covenant-hcp-phase-2/
│   ├── summit-q2-campaign/
│   └── clean-desk-extract/
├── 2-areas/
│   ├── hines-creative-ops/
│   │   ├── clients/
│   │   │   ├── shaw-plumbing/    # ongoing relationship docs
│   │   │   ├── covenant-wildlife/
│   │   │   ├── summit-energy/
│   │   │   └── wellness-oasis/
│   │   ├── finances/
│   │   └── playbooks/
│   ├── fleet/
│   │   ├── doctrine/
│   │   │   ├── 01-ethos.md
│   │   │   ├── 02-source-order.md
│   │   │   └── 03-conventions.md
│   │   ├── protocols/
│   │   │   ├── 01-handoff.md
│   │   │   ├── 02-compaction.md
│   │   │   └── 03-fast-gate-validation.md
│   │   ├── variants/
│   │   │   ├── pepper.md
│   │   │   ├── stark.md
│   │   │   └── nagatha.md
│   │   ├── machines/
│   │   └── state/
│   ├── health/
│   └── personal/
├── 3-resources/
│   ├── api-references/
│   ├── design-swipefile/
│   ├── ad-copy-swipefile/
│   ├── prompt-library/
│   └── research/                  # outputs of research subagents
├── 4-archives/
│   ├── projects/                  # finished projects
│   ├── sessions/                  # NEW classified session-archives
│   │   ├── 2026/
│   │   │   ├── 05/
│   │   │   │   ├── 2026-05-11-mac-session-<id>.md
│   │   │   │   └── ...
│   │   │   └── 04/
│   │   └── 2025/
│   ├── doctrine-old/
│   └── clients-inactive/
├── +index.md                      # home MOC
├── +fleet-moc.md
├── +clients-moc.md
├── +variants-moc.md
├── +sessions-moc.md               # dataview-generated from archives
├── _templates/
├── _attachments/
└── _meta/
    ├── README.md
    └── conventions.md

Per-agent variant runtime folder (e.g. ~/.claude/variants/pepper/):

pepper/
├── 0-inbox/                       # incoming messages, unprocessed
├── 1-tasks/                       # active tasks (= Projects analog)
│   ├── 2026-05-11-shaw-canon-review.md
│   └── current.md → symlink to current task
├── 2-memory/                      # ongoing context (= Areas analog)
│   ├── soul.md                    # identity / persona
│   ├── user.md                    # context about Wes
│   ├── canon-rules.md             # role-specific rules
│   └── learnings.md
├── 3-reference/                   # docs Pepper might need (= Resources)
│   └── doctrine -> symlink to vault doctrine
├── 4-archive/                     # closed tasks, old handoffs
│   ├── handoffs/
│   │   └── 2026-05-11-1430.md
│   └── tasks/
├── _logs/                         # raw transcripts, sidecar state
├── _meta/
│   └── README.md
└── CLAUDE.md                      # boot config, references the above

Per-project repo (e.g. ~/Work/clients/covenant/covenant-hcp-sync/):

covenant-hcp-sync/
├── apps/                          # if monorepo; else just src/
│   └── worker/
├── packages/                      # if monorepo
│   └── shared/
├── tools/                         # = scripts/; codegen, migrations
├── tests/
├── docs/                          # = Resources analog
│   ├── architecture.md
│   ├── deployment.md
│   └── decisions/                 # ADRs
├── archive/                       # old migrations, deprecated code
├── .claude/                       # repo-scoped Claude config
│   └── CLAUDE.md
├── README.md
├── package.json
└── wrangler.toml

The mapping is:

Vault	Agent Runtime	Repo
`0-inbox/`	`0-inbox/`	(n/a)
`0-daily/`	`_logs/`	git history
`1-projects/`	`1-tasks/`	`apps/`
`2-areas/`	`2-memory/`	`packages/`
`3-resources/`	`3-reference/`	`docs/`
`4-archives/`	`4-archive/`	`archive/` + git tags
`_templates/`	(n/a)	`tools/`
`_attachments/`	(n/a)	(assets in app)
`_meta/`	`_meta/`	`README.md`

This is “ONE canonical layout used everywhere” with surface-appropriate substitutions. The verbs map even when the nouns change.

Recommendation #2 — Pure PARA + Daily

Simpler, less innovative, very well-documented. Use if Wes doesn’t want to think about the agent runtime parallel and is OK letting agent folders follow their own convention. Loses the unifier benefit but cuts learning curve in half.

Recommendation #3 — Pure Johnny.Decimal

Only if Wes deeply values speaking addresses aloud and is willing to spend a weekend numbering. Penalty: ~10-15% extra token cost on every agent read of every path. Not recommended.

Recommendation #4 — LYT + flat root

If Wes hates folders and trusts links + Dataview + Bases entirely. Could work for the vault but breaks everywhere else.

Recommendation #5 — Kepano-flat (most notes at root)

Too flat for a vault that mixes business + fleet + sessions + research. Wes’s vault has heterogeneous content; root-flat assumes everything is “a personal note.” Not a fit.

10. Anti-Patterns (consensus across retrospectives)

From xda-developers.com/avoid-obsidian-setup-mistake-organized-notes/, makeuseof.com/i-wish-i-knew-these-before-creating-my-obsidian-vault/, makeuseof.com/beginner-mistakes-obsidian/, brandonkboswell.com/blog/Should-you-use-PARA-in-Obsidian, HN thread 36308366, and the Obsidian forum threads on PARA and JD:

Empty pre-created folders. Don’t make 4-archives/clients-inactive/ if you don’t have any inactive clients. Create folders the moment you need them, not the moment you imagine them.
Mixing taxonomy levels. Don’t put 2026-projects/ next to clients/ — one is time, one is entity. Pick one axis per level.
Deep nesting (>3 levels). Every additional level is a tab-completion round-trip for both humans and LLMs. vault/areas/fleet/variants/ pepper/memory/learnings.md is already 5 levels; that’s the ceiling.
Inconsistent capitalization and separators. Pick one rule (Wes’s existing fleet leans kebab-case-lowercase) and apply it everywhere. Projects/ and 1-projects/ and 01_projects/ in the same tree is chaos.
Numbering when you don’t need positional ordering. JD-style numbers are pure cost unless you genuinely need to say “twenty-two-oh-four” out loud or maintain stable addresses across systems.
Letting the daily folder rot. If you don’t journal daily, don’t keep an empty daily folder — it shames you. Either commit or delete.
Putting attachments in Resources/. Attachments are bytes, not knowledge. Keep _attachments/ separate. Otherwise grep hits binary files and graph view bloats.
One mega-folder for “Misc” or “Stuff”. Becomes a black hole. Force yourself to file or delete.
Maintaining MOCs manually past your tolerance. If you can’t update them weekly, generate them with Dataview / Bases and let staleness show automatically.
Symlinking vault into a repo or vice versa. Tempting but breaks Obsidian’s index, breaks git ignores, and confuses LLM agents about where the canonical copy lives. Keep them separate; reference via absolute paths.
Naming variants after personas without canonical-name fields. Wes’s fleet already hit this — runtime IDs drift, peer IDs roll; only canonical_name is stable.
Storing secrets in any of the four PARA buckets. Secrets live in ~/.claude/docs/integrations-keys.env (per Wes’s existing protocol), never in vault, never in repo. Anti-pattern is dragging them into “Resources/api-keys” because it feels reference-y.
Letting Archives become a write-only graveyard. Run a quarterly pass: real-archive (move to slower storage) or delete. Otherwise 4-archives/ becomes 80% of the vault and clutters search.
Treating any framework as canonical without local fitting. Every framework’s authors explicitly say “adapt, don’t adopt.” The PARA starter kit creator: “BASB and PARA are just the bare minimum working minimum that you build upon, not a final done product.”

11. Where Wes’s current state already aligns

Quick audit against existing fleet conventions:

Convention	Already aligned?
`~/Work/clients/<client>/`	Yes — solo-dev std
`~/Work/tools/<tool>/`	Yes — solo-dev std
`~/Work/active-projects/`	Yes
`~/jarvis/hinesipedia/Fleet/...`	Areas-equivalent
`~/jarvis/hinesipedia/Projects/`	(verify if exists)
`~/jarvis/hinesipedia/working/`	Inbox-equivalent
`~/.claude/docs/`	Resources analog
`~/.claude/projects/<cwd>/memory/`	Per-variant memory
Daily notes in vault	(verify)
Session archives	NEW — about to add

Wes is already 70% on Recommendation #1 without realizing it. The lift is:

Decide whether to formalize 0-inbox and 0-daily at the vault root (most of the value).
Decide whether to number the four PARA tops (1-projects/) or leave them unnumbered (projects/). Numbering helps deterministic sort and is fleet-grep friendly. Strong vote for numbering.
Standardize the session-archive subtree as 4-archives/sessions/YYYY/MM/ rather than a sibling top-level. Keeps the top short.
Adopt the verb-mapping table (section 9) as the unifier doc and reference it from _meta/conventions.md in each surface.

12. Sources

PARA:

Tiago Forte, BASB overview: https://fortelabs.com/blog/basboverview/
Matt Giaro, PARA in Obsidian: https://mattgiaro.com/para-obsidian/
Obsidian forum, PARA Starter Kit: https://forum.obsidian.md/t/para-starter-kit/223
PARA critique thread: https://forum.obsidian.md/t/the-para-method-and-the-hard-facts-of-life/22279
Brandon Boswell, Should you use PARA in Obsidian: https://brandonkboswell.com/blog/Should-you-use-PARA-in-Obsidian
Sebastien Dubois, PARA: https://www.dsebastien.net/2022-04-26-para/
Obsibrain Docs: https://docs.obsibrain.com/features/p.a.r.a-folder-structure

Johnny.Decimal:

Canonical site: https://johnnydecimal.com/10-19-concepts/11-core/11.02-areas-and-categories/
System expansion: https://johnnydecimal.com/10-19-concepts/13-system-expansion/13.01-introduction/
Robb Knight implementation: https://rknight.me/blog/using-the-johnny-decimal-system/
Luca Franceschini, JD + Second Brain: https://lucaf.eu/2023/02/23/luca-decimal.html
Sebastien Dubois, JD: https://www.dsebastien.net/2022-04-29-johnny-decimal/
Cody Burleson, JD critique: https://medium.com/@cody.burleson/patterns-for-pkm-johnny-decimal-system-5753774e77fd
HN discussion: https://news.ycombinator.com/item?id=36308366
Ellane W, JD + Obsidian: https://medium.com/produclivity/using-johnny-decimal-with-obsidian-solved-all-my-organising-woes-68c8c5c3dcc9

Zettelkasten:

Obsidian Rocks Zettelkasten guide: https://obsidian.rocks/getting-started-with-zettelkasten-in-obsidian/
Bryan Hogan, second brain Zettelkasten: https://bryanhogan.com/blog/obsidian-zettelkasten
Theo Stowell, fusing PARA + Zettelkasten: https://medium.com/obsidian-observer/fusing-the-two-most-powerful-note-taking-systems-in-obsidian-331d7c4fb2df
Atomicity critique: https://forum.obsidian.md/t/debating-the-usefulness-of-atomic-notes/38077
Obsidian-as-confusing-Zettelkasten: https://forum.zettelkasten.de/discussion/1745/why-does-obsidian-lead-to-a-confusing-zettelkasten

LYT / MOCs:

LYT site: https://www.linkingyourthinking.com/
Nick Milo, age of the linked note: https://medium.com/@nickmilo22/reflecting-on-the-age-of-the-linked-note-ff13945d6af4
Abilian Innovation Lab summary: https://lab.abilian.com/Business/Personal%20Knowledge%20Management/Linking%20Your%20Thinking/
Tara H, ACE framework: https://medium.com/@THLiterary/nick-milo-s-new-lyt-framework-how-to-ace-it-40f83942c48e

CODE / BASB:

Forte Labs overview: https://fortelabs.com/blog/basboverview/
Vic Montano, CODE methodology: https://thevicmontano.substack.com/p/a-second-brain-the-ultimate-creativity
Web Highlights guide: https://web-highlights.com/blog/master-your-second-brain-how-to-use-the-code-technique/

PARA + Daily / Periodic notes:

Obsidian Daily Notes docs: https://help.obsidian.md/plugins/daily-notes
Dann Berg, daily template: https://dannb.org/blog/2022/obsidian-daily-note-template/
Obsidian Rocks daily: https://obsidian.rocks/my-current-daily-note-in-obsidian/
LifeOS / PARA + Periodic: https://forum.obsidian.md/t/lifeos-building-my-second-brain-with-obsidian-para-method-periodic-notes-fullcalendar/62934

Power user vaults:

Kepano (Steph Ango): https://stephango.com/vault, https://github.com/kepano/kepano-obsidian
14 example vaults: https://forum.obsidian.md/t/14-example-vaults-from-around-the-web-kepano-nick-milo-the-sweet-setup-and-more/81788
Sebastian Witowski: https://switowski.com/blog/obsidian/
Obsidian Mate vault gallery: https://obsidianmate.com/vaults
Excellent Physician: https://www.excellentphysician.com/post/how-i-organize-my-obsidian-vault
r/ObsidianMD analysis: https://www.aitooldiscovery.com/guides/obsidian-reddit
PARA + Zettelkasten template: https://forum.obsidian.md/t/para-zettelkasten-vault-template-powerful-organization-task-tracking-and-focus-tools-all-in-one/91380

Monorepos:

Turborepo structuring: https://turborepo.dev/docs/crafting-your-repository/structuring-a-repository
pnpm workspaces: https://pnpm.io/workspaces
Nx + pnpm: https://nx.dev/blog/setup-a-monorepo-with-pnpm-workspaces-and-speed-it-up-with-nx
2026 monorepo tools comparison: https://viadreams.cc/en/blog/monorepo-tools-2026/
Feature-Sliced Design: https://feature-sliced.design/blog/frontend-monorepo-explained

DDD:

Martin Fowler, Bounded Context: https://martinfowler.com/bliki/BoundedContext.html
Steve Scruz, DDD file structure: https://dev.to/stevescruz/domain-driven-design-ddd-file-structure-4pja
Bytescrum DDD folder example: https://blog.bytescrum.com/a-comprehensive-guide-to-domain-driven-design-ddd-with-a-practical-folder-structure-example
DDD-crew Bounded Context Canvas: https://github.com/ddd-crew/bounded-context-canvas

Solo dev / freelance:

Marc Ashwell: https://marcashwell.medium.com/how-to-organize-your-client-folders-24a24d78e2e6
Dave Woods: https://www.dave-woods.co.uk/project-folder-structure-for-a-web-designer/
freelancermap: https://www.freelancermap.com/blog/organising-files-as-a-freelancer/
99designs: https://99designs.com/designer-resource-center/freelancer-toolkit/organize-your-work
DEV community, manage projects: https://dev.to/cecilelebleu/how-i-manage-my-projects-folders-and-files-38d3

Python project layouts:

PyPA src vs flat: https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/
Real Python project layout: https://realpython.com/ref/best-practices/project-layout/
Hitchhiker’s guide: https://docs.python-guide.org/writing/structure/

AI agent runtime layouts:

MindStudio agentic OS file structure: https://www.mindstudio.ai/blog/agentic-operating-system-file-structure-context
AGENTS.md guide: https://ai-insider.io/ultimate-agents-md-guide/
Satheesh Kumar, organizing files for agentic AI: https://medium.com/@sathee12/organizing-files-for-agentic-ai-systems-my-rough-draft-e413dbe241d7

Anti-patterns:

XDA, vault mistakes: https://www.xda-developers.com/avoid-obsidian-setup-mistake-organized-notes/
MakeUseOf, beginner mistakes: https://www.makeuseof.com/beginner-mistakes-obsidian/
MakeUseOf, vault retrospective: https://www.makeuseof.com/i-wish-i-knew-these-before-creating-my-obsidian-vault/
Obsidian Rocks folders: https://obsidian.rocks/how-i-use-folders-in-obsidian/
Kara Monroe vault rebuild: https://iwannabemewhenigrowup.medium.com/the-obsidian-vault-rebuild-geeking-out-on-folder-structures-and-the-first-plugin-excalidraw-babdb1cfed00