naudachu
1815d91cdf
A discussion leaves behind a directory of markdown somewhere outside this repo, and the only durable home for it is the Gitea wiki. Getting it there by hand means re-deriving the same three things every time: what each file should be called, where it goes, and whether the page already exists. Two skills wrap that, along the split the repo already uses. `skills/page` is domain, offline, stdlib-only, and knows nothing about Gitea. It imports a directory into a space under `tmp/wiki/`, titles every file, records the result in `.pages.json`, and writes the index. `skills/wiki` is the bridge — `wikimap.py` translates, and the transport is `_gitea.py`, the same one the issue side uses. There is no second transport, and `tea` has no wiki subcommand to offer one. The Gitea wiki is flat, and that fact shapes everything There are no directories. A title of `a/b` is stored as one file named `a%2Fb.md`, and Gitea escapes it by rules of its own: space becomes `-`, `/` becomes `%2F`, and a literal `-` forces a trailing `.-` marker so the two stay distinct. `Chain decisions — DC` under two levels of prefix comes back as `Simple-Chains%2FParked%2FChain-decisions-%E2%80%94-DC`. So `sub_url` is the identity, it is read back from whatever the API returned, and it is never constructed. One built by hand that is almost right does not fail — it creates a second page and abandons the first. And a real subdirectory committed into a wiki's git repository is a ghost: the file exists, the API and the web UI do not see it. `folder/page.md` in this repo's own wiki is one. Nothing here clones a wiki repo. A title is a decision, not a derivation Titles come from the first heading, because there is no mechanical route from `03-q-01-do-we-know-the-chain-participant-by-name.md` to `Q-01. Do We Know the Chain Participant by Name`. But they are derived exactly once. A re-import replaces bodies and keeps titles, so editing a heading cannot rename a published page — which would not rename it, it would publish a second one. `--retitle` opts in. It finds the prior entry by `source` rather than by path, because the path is derived from the title and a retitle moves it; looked up by path the page would read as new and the next push would duplicate it. The old file goes, `sub_url` comes along, and `pushed` is cleared — a rename can leave the body byte-identical, and push decides by body hash alone, so a stale hash would skip the rename forever. Ordering is a `NN-` file-name prefix and never reaches the title. `00-` means "this is the directory's own page", and that page is named for the directory, not for its own heading: a child's title has to extend its parent's exactly, and `ideas/00-intro.md` opens with "Ideas for chain business requirements". Path collisions are reported and never resolved. Picking a winner is how a discussion loses a document. The index is navigation, not decoration Nothing draws a tree from flat titles. `page_index.py` writes one as an ordinary page, nested by title depth rather than by manifest path order — those disagree, since on disk `Top/System.md` sorts before `Top/Ideas/Scale.md` while in the hierarchy System is a child and Scale a grandchild. A parent with no page of its own still gets a node, so its children are not hidden. Links use `sub_url` when there is one and Gitea's `[[Title|label]]` syntax when there is not, so the order is push, rebuild, push. The same stances as the issue store, for the same reasons Pull overwrites, push is additive and never deletes, change detection is one hash and there is no drift model. A page with no `sub_url` has never been published, and that is a durable state. Issues gain a `wiki:` field holding page titles — titles, not URLs, so the reference stays in the domain. It already round-trips as a foreign key; this documents it. Verified against a live Gitea 1.26.1: create, update with a message, unchanged-skip, prefix-filtered pull, byte-identical round trip, and the per-page revision history carrying the operator's own words. The probe pages were deleted afterwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.9 KiB
name, description
| name | description |
|---|---|
| page | Organize a discussion's artifacts into a named, ordered tree of wiki pages — import a directory of markdown, give every file a title, build the index, see what a space holds. Entirely offline; pages are local markdown files and need no wiki. Load when the user asks to turn notes/artifacts into wiki pages, organize or re-title a page tree, or rebuild a table of contents. For fetching from or publishing to a Gitea wiki, load /tea:wiki instead. |
/tea:page — discussion artifacts as a page tree
A discussion produces artifacts wherever the discussion happened — a directory
of markdown with numbered files and subdirectories. This skill turns that into
a space: a named, ordered tree of pages with a manifest, living under
tmp/wiki/.
Nothing here touches the network. No tea, no Gitea, no login. A space that
never leaves this machine is a finished thing, not a draft waiting for an
upload. Publishing is a separate, optional layer — /tea:wiki.
Read references/pages.md before importing or
re-titling. It is the single source of truth for titles, ordering, paths, the
manifest, and the index.
Identity: the title
Simple Chains/Ideas/Chain core. The / is the only hierarchy there is — the
wiki this feeds is flat and has no directories. The local path is derived from
the title (Simple-Chains/Ideas/Chain-core.md); the reverse never happens.
A title is chosen once, at import or at pull, and then it is a fact in the
manifest. Editing a heading does not rename a page. Renaming is --retitle,
and on a published page it orphans the old one.
Scripts
All offline, all in <skill-base-dir>/scripts/.
| Script | What it does |
|---|---|
page_import.py --from DIR [--space S] [--prefix T] |
copy a directory of markdown into a space, titling every file |
page_index.py [--space S] [--prefix T] |
write the table-of-contents page — the navigation the flat wiki cannot provide |
page_ls.py [--space S] [--prefix T] |
the tree, the titles, and one sync-state tag per page |
page.py |
the domain module the others import — not a command |
tmp/wiki/claude-skills/tea/ a space
.pages.json the manifest — titles, order, sync bookkeeping
Simple-Chains.md the index page
Simple-Chains/Ideas.md title: Simple Chains/Ideas
Simple-Chains/Ideas/Chain-core.md title: Simple Chains/Ideas/Chain core
The usual run
python3 scripts/page_import.py \
--from ~/proj/tmp/simple-chains \
--space claude-skills/tea --prefix "Simple Chains" --dry-run
--dry-run first, always: it prints every path and the title it would get, and
that listing is the only chance to catch a heading that titles a page badly
before the name becomes a decision. Drop the flag to write.
Then the index, then look at it:
python3 scripts/page_index.py --space claude-skills/tea --prefix "Simple Chains"
python3 scripts/page_ls.py --space claude-skills/tea --prefix "Simple Chains"
page_ls.py tags each page local (never published), synced (published and
unchanged), or ahead (edited since it was published). local is a complete
state.
Where the cache is
<repo root>/tmp/wiki — not tmp/wiki relative to wherever you are
standing. The scripts resolve it by walking up from their own file to the
nearest .git or AGENTS.md, so they all see one cache no matter which
directory they are run from.
--out overrides that and is taken literally: an absolute path is used as
given, a relative one stays relative to the current directory.
Re-importing is the normal refresh
The discussion continues, the artifacts change, run the same import again.
Bodies are replaced, titles are kept, sub_url and the rest of the wiki
bookkeeping survive — so the next push updates the pages that already exist
instead of publishing a second copy of each.