jdex

Prerequisites

• This skill requires the johnnydecimal skill for JD system context.
• This skill finds things and writes notes. It moves no files itself. The JD CLI moves them, under Moving in and Filing below. Without the CLI, tell the user where each file belongs and let them move it.

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

Where the configuration file and the CLI are

The JD CLI knows the paths of its files. Get each path from the CLI. Do not calculate a path yourself if the CLI can give it to you.

• The program is ~/.local/share/johnnydecimal/cli/bin/jd. Nothing has to be sourced first.
• ~/.local/share/johnnydecimal/cli/bin/jd paths config prints the path of the configuration file.
• ~/.local/share/johnnydecimal/cli/bin/jd paths prints three paths: the configuration file, the journal, and the folder that contains the CLI.

Before version 4.0, the CLI kept all its files in ~/.jd. The program was ~/.jd/cli/bin/jd. The configuration file was ~/.jd/config.json. A CLI that is still in ~/.jd continues to operate.

• If the program is not at the first path, run ~/.jd/cli/bin/jd help. If that command runs, use ~/.jd/cli/bin/jd in each command that this skill gives.
• If the CLI is in ~/.jd, tell the user one time. Tell them that you can update the CLI and move it. install_cli on the server has the steps. Ask before you do the steps. Do not move the files yourself.
• If paths gives an error, the CLI is older than 4.0. Then the configuration file is $JD_CONFIG if the user set it. If the user did not set it, the configuration file is ~/.jd/config.json. Tell the user one time that the CLI is old, and that install_cli has the steps to update it.
• If jd prints a line about a file in ~/.jd, the CLI is 4.0 or later, but that file is still in ~/.jd. Tell the user one time. jd agent-setup prints a prompt that tells you how to move the file. Ask before you follow the prompt.

If there is no CLI at either path, use the first item in this list that applies:

1. $JD_CONFIG, if it is set. $JD_CONFIG is the path of the configuration file.
2. $XDG_CONFIG_HOME/johnnydecimal/config.json, if $XDG_CONFIG_HOME is set.
3. ~/.config/johnnydecimal/config.json.
4. ~/.jd/config.json, if there is no file at the path from item 2 or item 3.

The JDex and the filesystem

There are two parallel structures. Both use the same JD hierarchy. Their paths come from the configuration file, the canonical Johnny.Decimal client config. Find the configuration file as the section above tells you. Read it one time, 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, the JD CLI writes it. Run ~/.local/share/johnnydecimal/cli/bin/jd agent-setup: it prints a prompt in the user's voice that finds their systems, confirms each root, and writes the configuration file. Follow it. If the CLI is not installed, call install_cli on the server first. This skill keeps no copy of those steps and never writes the file from memory. Ask before writing.

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

• The configuration file 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.

The filesystem always nests like this. The JDex does not, so establish its layout once, with a single ls of $JD_JDEX:

• Nested — the root holds area folders, 10-19 Life admin. A note is at $JD_JDEX/10-19*/13*/13.42*. The JDHQ Obsidian downloads default to this.
• Flat — the root holds the notes themselves, 13.42 Some title.md. A note is at $JD_JDEX/13.42*. A notes app with no folders gives you this, and it is offered as a download too.
• One file — the root is a single .md. Read it and work inside it.

Both of the first two are normal. Do not treat a flat JDex as a broken nested one.

So you can go straight there with a single glob:

• JDex note: $JD_JDEX/13.42* when flat, $JD_JDEX/10-19*/13*/13.42* when nested (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 use ~/.jd/config.json for this. That file is the configuration file of an older CLI, and it 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, following the JDex layout above: $JD_JDEX/13.05* when flat, $JD_JDEX/10-19*/13*/13.05* when nested. 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.

Read this	Write this
13.01 Inbox for category 13	13.05 AI for category 13 ✨
10.01 Inbox for area 10-19	10.05 AI for area 10-19 ✨
00.01 Inbox for the Small Business System	00.05 AI for the Small Business System ✨

• 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 here. The filesystem folder is not yours to make. This is the one note you write by hand. Every other new ID goes through the CLI, under Creating things below.

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.

Creating things

The JD CLI makes new IDs and work packages. Never write a new ID's note or folder by hand. The CLI picks the next free number, fills the note from the user's template, and makes the folder. Each of those is easy to get wrong by hand.

The program is ~/.local/share/johnnydecimal/cli/bin/jd. Nothing has to be sourced first. Check it with ~/.local/share/johnnydecimal/cli/bin/jd help. If the program is not there, it can be in ~/.jd/cli. Refer to the section Where the configuration file and the CLI are, above.

• A new ID: ~/.local/share/johnnydecimal/cli/bin/jd new id 21 A title. This makes the next free ID in category 21. Give 21.34 instead of 21 for that exact ID. The user names the category. A new ID needs no active ID first.
• A new work package: ~/.local/share/johnnydecimal/cli/bin/jd new wp 21.41 A title. This makes the next free W number, and the package belongs to 21.41.
• The title needs no quotes. It is every word up to the first word that starts with --.
• --dry-run says what it would make, and makes nothing. Use it when you are not sure.
• --json prints one object to branch on: { "ok": true, ... } or { "ok": false, "code": "...", ... }. Its toFill list names the template tokens you gave no value. Each token has a flag: {{?SCOPE}} is --scope. Ask the user for the values, or pass them when you know them.
• With more than one system, --system goes first: ~/.local/share/johnnydecimal/cli/bin/jd --system P76 new id 21 A title.
• If jd says beta is off, the CLI is older than 4.2.0. Tell the user. install_cli on the server has the update steps. Ask before you run them.

The ID it made is your active ID from then on. Read its note before you write to it. The template shapes it, and the user's conventions are in there.

If the CLI is not installed, call install_cli on the server and follow its steps. If the server is not connected either, stop and say so. Do not make the ID by hand.

The one exception is the AC.05 note, above. It has a fixed number, and its folder is not yours to make, so you write that note yourself.

Moving in

Moving in puts the user's existing files into the system they have installed. The server's move_in tool holds the process. This skill holds the rules for the CLI and the note, and nothing more. When the user wants their existing files in their system, call move_in with the system, las or sbs. Follow the text it returns.

• Files move with ~/.local/share/johnnydecimal/cli/bin/jd move. Use that full path. Never run mv. Never delete a file or a folder. The CLI moves files, not you. The same rule holds for new IDs, under Creating things above.
• The run's state lives in the 00.05 note, under one heading, ## yyyy-mm-dd Moving in. move_in names the sub-headings under it. Read that section first in every session. The section is yours. Mark it the way Writing things, above, says.
• Reading inside files is the user's choice. move_in asks once and records the answer in that note. Keep to the recorded answer. Do not ask again.
• Filing, below, says what a good name and a good subfolder are.

Filing

Filing puts a file into an ID, under a name that sorts. It happens during Moving in, and at any other time the user asks. Which ID the file goes in is decided under Which ID to use, above. This section is about the target: the name, the subfolder, and the note line.

The published rules for names and subfolders live on the server. Call get_documentation for naming-files and for subfolder-patterns, and follow what they say. Do not keep a copy here.

move_in says when to propose and that the user says yes per batch. This section says what a good name and a good subfolder are. Neither repeats the other.

How it moves

The move is one jd move call, the same as Moving in says. Never run mv, not even to rename. jd move renames the file as it moves, and puts it in a subfolder of the ID, which it makes when needed. Run ~/.local/share/johnnydecimal/cli/bin/jd move --help for the syntax. Do not work from memory. If the help lists neither, the CLI is old. Tell the user. install_cli on the server has the update steps. Ask before you run them.

The proposed name

Propose a better name for every file you file.

• Date first, yyyy-mm-dd, when you can find one. Look in the file name, then the file metadata, then the content. Read the content only if the user allowed it. Moving in, above, records that answer.
• Use yyyy-mm or yyyy when that is all you know. A file with no findable date gets no date. Never invent one.
• Then what the thing is, then who it is from or for. For example, 2024-03-31 Statement ANZ.pdf. Sentence case. Spaces between the words.
• Keep a reference number from the original name, for example an invoice number.
• Drop a counter like (1), copy, or FINAL. Drop a version tag when there is only one version. Drop a camera or scanner prefix such as IMG_ or Scan.
• Drop any word the ID's own name already says. In 13.31 Purchase receipts, a file does not need "receipt" in its name.
• Keep the extension as you found it.

Subfolders

A subfolder needs two things. Without both, the files go loose in the ID.

1. A group. Several files that share one thing: one account, one trip, one supplier.
2. A pattern. One of the three on the subfolder-patterns page: date, alphabet, or 10–90.

About five files is a guide for "several". You make the call. The user says yes before you make a subfolder.

The note line

For every subfolder you make, add one line to the ID's JDex note, below the ---. The line gives the subfolder's name and what it holds.

- Subfolder `Statements ANZ`: monthly statements, one file per month.

Mark it the way Writing things, above, says.

A folder that moves whole

• The folder gets a proposed name, like any file.
• Look inside it. If the files inside follow a pattern, move the folder as you found it.
• If the inside is a mess, propose a rename pass and ask. You decide which case it is.
• Never rename inside a folder without asking.

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 tells you the layout. A few lines when nested, one line per ID when flat. If it is a single file, read that file and stop here.
2. Nested — the root gave you the areas. List the categories inside the area the question points at, then the .md files in the likely category. If you can't tell which area yet, list the categories across all of them. Still small. Flat — the root already gave you every entry. Filter it by category, e.g. ls "$JD_JDEX"/13.*.
3. 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.