chemenu/instructions/page-lifecycle.md

type, name, description

type	name	description
types/instruction.md	page-lifecycle	Rename a page, delete one, or drop a single cross-reference without breaking the links that point at it.

Rename, delete, or unlink a page

A page's title is the wiki's only identifier for it. The same title appears in other pages' [[wikilinks]], in the [[Title]] a [^cite-id] footnote definition points at, and in frontmatter reference arrays (related:, sources:, entities:, concepts:).

Never move, rename, or delete a page file by hand, and never edit a reference array by hand. Each of the commands below rewrites all three places at once; hand-editing rewrites one and leaves the others pointing at nothing.

Rename

tools/wikitool rename --from "<Old>" --to "<New>" --dry-run   # see the blast radius first
tools/wikitool rename --from "<Old>" --to "<New>"

Repoints body wikilinks (aliases and anchors preserved), a citation id derived from the old title (both its Footnotes definition and every [^cite-id] reference to it), the page's own H1, and every frontmatter reference array the type declares in page_ref_fields:.

If --from is not a page but is referenced, rename instead repoints those references onto the existing --to page and moves nothing. That is the fix for a reference spelled act_runner when the page is Act Runner.

Delete

tools/wikitool rm --page "<Title>" --dry-run
tools/wikitool rm --page "<Title>"

It refuses while other pages still reference the page. That refusal is information, not an obstacle: show the user the inbound list, and only re-run with --yes once they approve.

It strips reference-array entries and bare - [[Title]] / - **label:** [[Title]] bullets. It leaves prose mentions and inline citations in place and reports them - those are an editorial fix afterwards, not a reason to retry the command.

Move

tools/wikitool move --page "<Title>" --dry-run   # see where it would go first
tools/wikitool move --page "<Title>"
tools/wikitool move --reconcile --dry-run         # every misplaced page at once
tools/wikitool move --reconcile

Moves the page's file to the directory its type-spec computes for its current frontmatter - base_dir + layout, the same rule new places a page by when it is first created. The destination is never chosen by hand: there is no --to <dir>. Only the file moves - no body, no frontmatter field, and the title (the wiki's only identity for a page) never changes, so no reference anywhere in the wiki needs updating.

--reconcile applies the same rule corpus-wide in one call; a second run reports nothing left to do. wikitool lint's Misplaced Pages finding is the advisory this fixes - it is not a hard error, so an unreconciled corpus is not a broken one, only one move would tidy.

A destination that already holds a file with the page's name is refused, not silently overwritten - that only happens on a pre-existing duplicate-title collision, which lint's Duplicate Titles finding reports separately.

Drop a single reference

tools/wikitool xref remove --a "<A>" --b "<B>"

Clears <B> from every reference field <A>'s type declares, plus the matching bullets. --b need not still exist as a page, which is how a reference left behind by an earlier hand-edit gets cleared. Idempotent.

Afterwards

Always close out with publish-cycle.md, using --op rename, --op delete, or --op move. A move changed no reference, so run wikitool index rebuild rather than sources rebuild-index - the catalog is built from where a page's file sits, and nothing else about it moved. Then confirm nothing was left dangling:

tools/wikitool lint

lint reports every reference still pointing at nothing, and every page still not at its computed location.

Scope

This is for pages under kb/. Contracts, instructions, skills and type-specs are not pages - they are moved with git mv, and their inbound links are ordinary markdown paths that have to be updated by hand.