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.

Contents

• Rename
• Delete
• Move
• Drop a single reference
• Afterwards
• Scope

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:.

--to has to be a valid, unique file name on every platform, and --dry-run refuses it the same way the real run does. The rule is in kb/CONTRACT.md § Titles are identifiers. Only --to is checked, so this is also the fix for lint's Unportable Titles finding: rename the page away from the title that breaks the rule. A change of case alone (Foo to FOO) is allowed.

The path kb/<collection>/<dir>/<New>.md also has to stay within the path budget of 160 characters (kb/CONTRACT.md § Titles are identifiers); rename refuses a longer --to before writing, --dry-run included. Renaming away from a too-long page is the fix for lint's Long Paths finding, and works the same way as for an unportable title.

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 - or one that differs from it only in case or Unicode normalization - is refused, not silently overwritten. That only happens on a pre-existing duplicate-title collision, which lint's Duplicate Titles and Unportable Titles findings report 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.