Jdex

Prerequisites

• This skill requires the johnnydecimal skill for JD system context.
• This skill finds things and writes notes. It does not move files. If the user wants documents filed into their JD filesystem, tell them where each one belongs and let them move it, or ask before you move anything yourself.

The jd MCP server

Johnny.Decimal knowledge comes from the jd MCP server, not from memory. The vault is the user's own overlay on it.

Call get_account first. It says which systems the account owns and whether it has Pro, so you know which tools will answer. The tool descriptions say what each tool does. Do not keep a second copy of them here.

Which source answers:

• Their notes, their files, their business. Answer from the vault. Do not go to the MCP for facts about the user's own content.
• How Johnny.Decimal itself works. Call the documentation tools. Do not answer JD concept questions from memory.
• The active ID. Read both, in the order below.

If the server is not connected, say so once, then continue vault-only. Say what is lost: without it you are answering Johnny.Decimal questions from memory, and that is where wrong answers come from. Connect with:

claude mcp add --transport http jd https://johnnydecimal.com/mcp

The JDex and the filesystem

There are two parallel structures. Both use the same JD hierarchy. Their paths come from ~/.jd/config.json, the canonical Johnny.Decimal client config — read it once at the start. Each entry in its systems list has:

• jdex — the index. Markdown notes, usually an Obsidian vault. This is where you look things up and write documentation.
• root — the filesystem. The actual files (PDFs, images, documents) in JD-structured folders.

With several systems in the config, use the entry marked default: true unless the user names another.

If the config is missing, or the system you want has no jdex path, find what's missing and offer to save it:

1. Look first. Areas are folders named NN-NN Title, e.g. 10-19 Life admin. A shallow search of ~/Documents, ~/Dropbox, ~/Library/Mobile Documents and similar usually finds the filesystem root. The index is often an Obsidian vault — look for a .obsidian folder.
2. Confirm with the user. Show what you found and ask if it's right. If you found nothing, ask them for the two paths.
3. Offer to write ~/.jd/config.json so nothing has to ask again. Ask before writing.

{
  "version": 1,
  "systems": [
    {
      "sys": "D25",
      "title": "Johnny.Decimal",
      "root": "/path/to/the/filesystem",
      "jdex": "/path/to/the/index",
      "default": true
    }
  ]
}

• root is the only required key. jdex is required for anything in this skill.
• sys is the system identifier, the SYS in SYS.AC.ID. Most people have one system and don't need it.
• default: true marks the usual system. It only matters when there is more than one.

If the file already exists, add to its systems list and leave the other entries alone. Never overwrite it.

Two files share the name config.json and answer different questions. Tell them apart by their keys:

• ~/.jd/config.json has a systems list. It says which systems exist and where they are. One per machine.
• .jd/config.json in a working folder has an id. It says which ID that folder is about. It never carries a systems list.

Neither overrides the other. If a folder one ever carries root or jdex, those win for that folder only.

In the examples below, $JD_JDEX and $JD_ROOT stand for these two paths. Substitute the real values — shell variables don't persist between your Bash calls.

The JD numbering makes paths deterministic. The digits of the ID give you the folders:

• ID 13.42 → 10-19*/13*/13.42*
• ID 63.14 → 60-69*/63*/63.14*
• Work package W0189 → W0000-9999*/W0189*

Work packages are an optional extra area, W0000-9999, holding IDs of the form W0189. They sit directly in that area with no category level. The name usually carries a ~ and a normal ID — W0189~21.41 — meaning that package belongs to 21.41. Glob on the number alone, W0189*, because the rest of the name varies. An entry may be a single .md or a folder of them.

So you can go straight there with a single glob:

• JDex note: $JD_JDEX/10-19*/13*/13.42* (the .md file)
• Filesystem folder: $JD_ROOT/10-19*/13*/13.42* (the actual files)
• Child entry: $JD_ROOT/10-19*/13*/13.42*/+Savings/

The numbers give you the path. Don't search for it.

Which ID to use

• Your active ID is determined once per session, in this priority order:

  1. An ID at the start of the current folder's name, e.g. 12.34 My folder, or W0189~21.41 Some package. This is the normal case. People open Claude directly in an ID folder, so check this first. Match NN.NN or WNNNN only. A category (13 Money) and an area (10-19 Life admin) are not IDs.
  2. A .jd/config.json naming the ID this folder is about: {"id": "12.34"}, plus "sys": "D25" when the user runs more than one system. Walk up from the working directory to the first one you find, stopping at the home folder. The nearest wins. Do not read ~/.jd/config.json for this; that file has no id.
  3. An ID at the start of a parent folder's name, nearest first. This covers working in a subfolder, e.g. 12.34 Receipts/2026-03.
  4. An ID the user explicitly provides when asked.

• Once an active ID is set, stick with it. All reads, writes, and documentation go to that ID's JDex entry.

• Do NOT browse, scan, or explore the JDex looking for other entries. The JDex is not a task list to trawl through. You work on the active ID.

• Only switch to a different ID if the user explicitly gives you a new one — e.g. "now look at 56.78" or "update W0189". Mentions of other IDs in note content, related links, or conversation context are NOT instructions to switch.

• If you're unsure whether the user wants a different ID, ask. Do not assume.

• If no folder in scope names an ID, there is no .jd/config.json, and the user hasn't provided one, STOP. Ask the user: "Which JDex ID should I use?" Do not search the JDex for a match, do not infer from the project name, and do not continue until the user gives you one.

Read the published ID first

Once the active ID is set, call get_id for it, once. Then read their own JDex note for the same ID.

• get_id returns the published definition of that ID, plus any supplements that apply to it: further readings, and ops manuals.
• An ops manual is a step-by-step procedure. If one comes back, tell the user it exists and offer to follow it. Fetch its body with get_id only when they accept. Do not paste it into their note.
• Their note beats the scaffold on how they actually work. The scaffold beats their note on what the published system says.
• Skip the call when the server is not connected, or when the account does not own that system. Say so once and carry on.

AC.05 is yours

AC.05 is the one ID you control. It holds two things: your own notes, kept so a later session can read them back, and the user's standing instructions for this part of their system. Nothing in the published Johnny.Decimal systems uses .05 for anything else.

Read them at the start of a session, narrowest first:

1. <category>.05. ID 13.33 gives 13.05.
2. <area management category>.05. Area 10-19 gives 10.05.
3. 00.05, for the whole system.

Glob them like any other ID, e.g. $JD_JDEX/10-19*/13*/13.05*. For a work package, use the ID it belongs to: W0189~21.41 gives 21.05, then 20.05, then 00.05.

• A narrower note beats a wider one on the same point. All three beat any general rule in this skill.
• Write to the one whose scope matches what you learned. Something true of the whole system goes in 00.05, not in 13.05.
• Anything the user tells you to follow is theirs. Record it as their instruction, and never edit or overrule it.
• Write what a later session needs and nothing more. This is a working note, not a log. Prune it when it goes stale.
• It is still their vault. AC.05 is not a place to put anything you would not show them.

Creating an AC.05 note

If the note you need isn't there, create it.

Name it AC.05 AI for <location> ✨. Copy <location> from the AC.01 note in the same place. AC.01 is the inbox, and it always exists.

• Leave the ✨ off if the neighbouring notes carry no emoji. The user has them turned off.
• Create it when you have something to put in it, not on the chance you might.
• The JDex note is all you create. The filesystem folder is not yours to make.

Use of the JDex

• Each entry is a Markdown file. To reach one directly, glob using the ID's digits, as above.
• When the user says "document this" or "write it up" in the context of this skill, they mean write it in the JDex entry — not in a local CLAUDE.md, README, or any other file.
• Follow links in the Related metadata field when they're relevant to the task. Reading a linked entry for context is fine — but the active ID does not change. All writes go to the active ID's entry unless the user explicitly gives you a different ID.
  • Create links where relevant. Use the shortest [[12.34 Title]] wiki-link syntax.

Writing things

• Before you write a note, read a neighbouring note in the same category. Match its layout — the user's own conventions beat any general rule.
• You are encouraged to update the JDex. The user MUST be able to find and review what you wrote. Mark it one of two ways.

  • If you wrote the file, or rewrote it in full, claim the whole file. Add an Owner: entry to the metadata block above the line. Use no inline tags.

    - Owner:
        - #claude
    

  • If the file is the user's and you are changing part of it, tag only what you changed.

    • A tagged header covers everything under it, subheaders included. Tag the header, nothing else.
    • Outside a tagged section, tag each line you added or changed.
    • Never tag a line the user wrote.

  • Either way, a wikilink you add above the line needs no tag. Above the line is the metadata block before the --- separator, where Related: and URL: live. Links there are navigation, not content.

• If you update something, follow wikilinks and check if anything in the linked pages needs to be updated.
  • If it seems obvious, just fix it.
  • If unsure, ask.

Finding things

The JDex is the starting point for every question about the user's own information. Whether they ask to find a file, trace a payment, understand a process, or answer any factual question about how things work — start with the index. Do not trawl the filesystem looking for a destination, and do not delegate to subagents: the skill context doesn't transfer. The index has the answer or links to it.

Step 1: narrow by structure, then list

The numbering exists so you don't need the whole index. Walk down it.

1. ls the jdex root. That gives you the areas, a handful of lines. It is normally a folder of area folders — if it turns out to be a single file, read that file and stop here.
2. List the categories inside the area the question points at. If you can't tell yet, list them across all areas. Still small.
3. List the .md files in the likely category. Those are the entry titles. Scan them for a match.

Entries are named AC.ID Title.md, or W0189~21.41 Title.md for a work package. AC.00 to AC.09 are system management, not filing destinations — ignore them. Do not read the note bodies at any step.

If the question points at no category at all, list every .md below the root in one pass:

find "$JD_JDEX" -name '*.md' -not -path '*/.obsidian/*'

That is the expensive option — on a large vault it runs to thousands of lines. Narrow first when you can.

Present the result as a JD path, e.g. 13 Money > 13.42+ Savings.

If nothing matches on titles, fall back to a content search: obsidian search query="..." format=json.

Step 2: go to the filesystem (if needed)

Only when the user wants the actual files, not just the JDex note. Go straight there with the glob:

ls $JD_ROOT/10-19*/13*/13.42*             # the ID folder
ls $JD_ROOT/10-19*/13*/13.42*/+Savings/  # a child entry

Not needed when they're just asking "where would I find X?".

Obsidian

• The JDex is usually an Obsidian vault. There will be a .obsidian folder at the root.
• Check for the obsidian command with command -v obsidian. It queries the vault directly.
• obsidian help lists every command. The useful ones here:
  • obsidian search query="..." format=json — searches content as well as filenames.
  • obsidian backlinks file="12.34 Some title.md" — what links here.
  • obsidian links file="12.34 Some title.md" — what this links to.