Map My Folder

Watch a folder get mapped.

One real repository, eight named stages: enumerate, find the repeating unit, classify, date every verdict with the command that decided it — then answer a question and stop.

Eight stages, the real artifact of each on screen. Captions carry the spoken track, which speaks each stage's on-screen headline and nothing else.

Seven card types. A closed set, each with a proof test.

Not adjectives — checks. A noun that fails all seven gets no card; it gets one line in the notes. That refusal is what keeps a map smaller than its territory.

Type	Proof test	What it hits
ENGINE	Two or more instances read it. Change it and all their behavior changes.	every instance, in place
BLUEPRINT	Instances contain its text rather than reference it.	future copies only
INSTANCE	It has a name an outsider recognizes — a market, a client, a product.	nothing; it is a leaf
SLOT	A named field inside an instance, same job in every instance.	every instance, now and later
MARKER	A value the machinery branches on. Signal, not content.	whatever branches on it
INSTRUCTION	It directs a human. Delete it and no run changes.	one reader, once
SURFACE	Someone who never opened the folder can encounter it.	outsiders, after publish

State is a second axis, and appearance never decides it.

Type says what a thing is. LIVE / LEFTOVER / GHOST says whether it is still alive — and no verdict ships without the command, path or status code that decided it.

the inversion rule

Look for who reads it first.

Big, current, well-written, and nothing reads it. Four lines the machinery branches on. A folder full of real data that the machinery never resolves into. Recent edits are evidence about an author, never about a reader.

evidence, in the same line

Or the verdict is UNVERIFIED.

A command and its output, a file:line, a status code, a byte count, a commit SHA. Not “appears unused”, not “looks legacy”. An honest gap is a map entry; a guess is a defect.

Two walks, kept apart.

They run in opposite directions and conflating them is the failure mode: a reading step inside a map-making pass writes cards before the collision pass; a map-making step inside a read turns a two-hop answer into a tour.

walk a — making the map

Cards are step seven.

Enumerate — never guess a filename
Find the repeating unit
Classify by type
Mark state, with evidence
Collision pass
Trace propagation: copy or reference
Cards, last

Done when the checks pass.

walk b — reading the map

Most reads stop at two.

Catalog
One card
Its Hits line — only if you are changing something
Stop

Done when the question is answered.

What a card looks like.

Eight lines, same order every time. This one is from the shipped worked example — a live instruction pointing at a path that has never existed.

06 · The Contributor Path instruction live → aims at a ghost

Evidence: Nothing under specialist/ reads it; delete it and no run changes. Its line 12 names case-studies/[slug]/README.md, and git ls-tree -r --name-only origin/main | grep … returns nothing — confirmed on origin, not just in a clone.
What it is: The door for the next contributed market.
Source path: CONTRIBUTING.md
Hits: The next contributor, once, at fork time. No run, no answer, no build.
Does not hit: The four existing case studies — the thing a reader reaches for first and wrongly. They agree with each other and disagree only with the sentence. Four contributions passed through this instruction and none followed it, which is the evidence that the sentence is the defect.
Done when: You have the real path from find, not from the instruction, and you have written the ghost down rather than closed it.

the hardest line is “does not hit”

It must name the noun a reader reaches for first and wrongly, and it must be mildly surprising. If you cannot name a plausible wrong reach, the card does not get written — that check alone deletes most of the cards a model would otherwise produce.

Two refusals. One of them runs.

No photocopy — three checks, all executable, plus the precedence line: if a card and the file disagree, the file wins and the card is wrong. No slurping — answering costs a catalog and one card; when mapping, you enumerate paths and sizes before opening anything.

$ python3 reference/checks/refusal-checks.py \
      --map reference/worked-example --territory ./your-market-realtor

card                           bytes    A cites  A       B       C       D
--------------------------------------------------------------------------------
01-the-engine.md                1940      86102  pass    pass    pass    pass
02-the-region-blueprint.md      2004      13454  pass    pass    pass    pass
03-a-market.md                  1847     139686  pass    pass    pass    pass
04-the-six-slots.md             2354      13454  pass    pass    pass    pass
05-the-marker-set.md            2057       5554  pass    pass    pass    pass
06-the-contributor-path.md      1805       3101  pass    pass    pass    pass
07-the-public-surface.md        2002     171963  pass    pass    pass    pass
--------------------------------------------------------------------------------

PASSED — every card is smaller than what it cites, shares no verbatim run over 200
characters with it, cites at least one path that resolves, and carries Hits, Does not
hit and Done when.

A smaller than what it cites · B no verbatim run over 200 characters · C cites a path that resolves · D carries Hits, Does not hit, Done when.

and it fails when it should — the same script on two deliberately bad cards

08-photocopy.md                 1614       1465  FAIL    FAIL    pass    FAIL
09-nopaths.md                    115          0  FAIL    pass    FAIL    FAIL

FAILED — 6 finding(s):
  · 08-photocopy.md: 1614 B card >= 1465 B cited (specialist/reference/region/glossary.md)
  · 08-photocopy.md: 200+ char run shared with specialist/reference/region/glossary.md
  · 08-photocopy.md: missing required line(s): Does not hit, Done when
  · 09-nopaths.md: no **Source path:** line
  · 09-nopaths.md: cites no path that resolves in the territory
  · 09-nopaths.md: missing required line(s): Does not hit, Done when

The worked example maps a real repository.

One specialist engine, one region blueprint copied into four populated markets, a public site. Seven cards, and the ceiling was reached — everything else is one line in the notes with the test it failed.

62files enumerated

7cards, the ceiling

1card, then stop

1ghost, left open

the cold run ships with it

With the catalog loaded — the configuration the README specifies — a fresh session with no memory and no coaching was asked “What is Services?”: it opened one card, answered with the collision, the routing row and a counting defect the repo did not know it had, and stopped. Runs given no framing at all took four reads; the transcript carries all three, including the one that never found the catalog and is the reason the door exists. Re-run any of them yourself — the configuration is a flag on the shipped tool, CATALOG_IN_CONTEXT=1.

A change question costs more than an identification one, by design — the walk says to read a card's Hits line only when you are changing something. Measured, same configuration: “I want to edit region/market.md — what else changes?” took one card plus the file itself. The same question with no framing at all took twelve.

proof from users

Nothing here yet. This build ships with its own gate output instead of borrowed praise.

What it refuses to map.

01A pile of one-offs. No repeating shape, so every card would be a summary. ls -lt is cheaper and tells you more.
02A single application where every file is unique. Nothing is copied, so nothing propagates. That wants a call graph.
03The methodology itself — a folder system about folder systems, this repo included. Mapping a method with the method returns a mirror.
04Anything it found broken. It marks the ghost and leaves it. A map that edits its territory while drawing it is a map of something that no longer exists.

A map of your folder, for the reader who has no memory.