[shovon]

Closes #104.

What changed

Code (packages/ledger/ledger.ts): #scan now skips dot-entries, files and folders, at the top of the ledger and inside writer directories. inspect already did this, and now both use one hidden() check. Before this change, .git, .stfolder and .stversions were each read as a writer, and a segment-named file inside .git was actually folded.

Spec (packages/ledger/multi-writer.md): a new section, "What else the folder may hold":

• The rule: a writer writes the format exactly, a reader ignores what the format does not name (as long as that does not change the fold), and a build may add files.
• Extras at the top are files. No name pattern for writer directories. Every non-dot folder at the top is still a writer, and a build that needs a folder there changes the format. Every writer directory so far is named by a UUID (randomUUID() before and after Swap @pbnotes/ledger for @pbnotes/append-only-log in the app #50, a UUIDv8 from openWriter). A pattern was considered, but it protects nothing until every build in use has it, and it would mean renaming every writer folder in the tests.
• Dot-entries are ignored everywhere and are not listed in status.ignored. Everything else the format does not name is still listed.
• The marker check is unchanged. A file at the top that several writers may create is created with an exclusive create, never rewritten, and has the same bytes on every build of one format version. And these extras are not a back door for format changes.
• Named extras: the list starts empty. AGENTS.md and the code that reads the list land in ledger: write an AGENTS.md at the root of a new ledger #63.
• "LEDGER is the only file at the top" now says "the only file required at the top". app/CLAUDE.md says the same.

For the reviewer

• Dot-entries are left out of status.ignored, not just skipped. That includes a .DS_Store inside a writer directory, which used to be listed. Common sync tools don't give conflicted copies names that start with a dot (Dropbox, Syncthing, iCloud, OneDrive), so this hides no conflict, and it keeps a sync tool's temp files out of the list.
• The branch merges main after Read quiet writer directories less often, and slow down in the background #101 (Decide how often the ledger looks for changes #52, cadence). The one conflict was the top-level loop in #scan: main's version is kept, with the dot-entry skip in front of it.
• app/CLAUDE.md says the marker's comment changed in Swap @pbnotes/ledger for @pbnotes/append-only-log in the app #50, but the spec says Give the ledger an instance interface: openOrCreate, writer, post, onEvent, close #45. That is left as it was.

Tests

• New test: a .git folder that holds a valid segment folds nothing. .stfolder, .DS_Store (at the top and in a writer folder) and a Syncthing temp file are neither read nor listed. A plain notes.txt at the top is still listed in status.ignored. The test failed before the fix (.git-1 was folded).
• npm test (138 tests across all workspaces) and npm run typecheck pass.

🤖 Generated with Claude Code