ledger: write an AGENTS.md at the root of a new ledger
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 72/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- markdown, typescript
- Domain
- backend
Research direction
Start in packages/ledger/ledger.ts, where openOrCreate creates a new ledger and createMarker writes the LEDGER marker; the new AGENTS.md should be written at the same point. Also read inspect() to confirm it accepts an AGENTS.md file without refusing the folder. Done when a freshly created ledger contains an AGENTS.md with the three points in the issue, an existing one is never overwritten (use an exclusive create), and inspect still accepts the folder.
Written by the indexing model from the issue text.
Description
An agent (Claude Code, Codex, etc.) dropped into a pbnotes project folder has no idea what it's looking at: a `LEDGER` marker and a pile of writer directories with segment files. It may try to "tidy" them, edit segments in place, or guess at the format.
Proposal
When `openOrCreate` creates a new ledger (alongside the `LEDGER` marker in `createMarker`, packages/ledger/ledger.ts), also write an `AGENTS.md` at the ledger root that:
- says this folder is a pbnotes ledger, written by the Pb Notes app;
- points to https://github.com/shovon/pbnotes for how to interpret the folder (format, multi-writer layout);
- warns not to modify, rename, or delete files here by hand: the content is append-only and shared with other writers.
Keep it short; the repo is the source of truth, the file is just a signpost.
Open questions
- Only on creation, or also when opening an existing ledger that lacks one? (Suggest: create-if-missing with `wx`, never overwrite, so a user's edits survive.)
- `inspect()` must keep treating an `AGENTS.md` as a non-ledger file it tolerates, not as a reason to refuse the folder.
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 1
- Avg merge
- 7h 50m
- Merged PRs (30d)
- 1
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from shovon/pbnotes
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
enhancement
Difficulty 4/5 3-5 days Newbie friendliness 30/100
-
enhancement
Difficulty 3/5 1-2 days Newbie friendliness 35/100
-
enhancement
Difficulty 3/5 Half a day Newbie friendliness 45/100
-
enhancement
Difficulty 3/5 Half a day Newbie friendliness 45/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Chocobozzz/PeerTube#7832 ·
Maintainers usually reply within 3 days
-
Pay to use?Open
Difficulty 1/5 Under an hour Newbie friendliness 66/100
darkreader/darkreader#16108 · 1 comment ·
Maintainers usually reply within 2 days
-
Add: Dak Nong TV SDOpencheck:passed streams:add
Difficulty 1/5 Under an hour Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
bug engine
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
frostney/GocciaScript#1746 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
agilepathway/label-checker#739 · 4 comments ·
Maintainers usually reply within 1 day