chemenu/instructions/page-lifecycle.md

type, name, description

type	name	description
types/instruction.md	page-lifecycle	Rename a page, delete one, move it, promote a section of one to a page of its own, 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
• Promote a section to its own page
• 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.

Promote a section to its own page

A subject can live as a section of another page until it earns its own - the shipped entities profile does this with people on their organization's page. Promoting one is not a move: a new page is born, and a section shrinks. No command does it in one step, because two of its steps are judgments - which edges meant the person and which the organization - and it is rare.

1. Create the page from the section's content, with the tool:

   tools/wikitool new entity --name "<Name>" --set entity_type=person --set provenance=<value>
   

   Move the section's prose into it, and its citations with cite add against the same sources.

2. Shrink the section on the parent page to one bullet under the heading that held it - - [[<Name>]] - <role> - and drop the section's own heading. With the heading gone, any link step 4 misses stops resolving and step 5 reports it, instead of landing quietly on a stub.

3. Connect the two - for a person, the membership edge on the new page:

   tools/wikitool xref add --a "<Name>" --b "<Organization>" --rel member-of
   

4. Find every link that meant the section, and point it at the new page:

   tools/wikitool search "[[<Organization>#<Name>"
   

   Search is literal by default, so the brackets need no escaping. Rewrite each hit to [[<Name>]], and move any edge on those pages that meant the person - consults: <Organization> for a client contact, say - from the organization to the new page with xref remove and xref add. An edge that meant the organization as a whole stays.

5. Check - tools/wikitool lint reports no broken_anchors and no broken_links. Then close out as for a new page.

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, --op move, or --op create for a promotion. 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.