---
type: types/instruction.md
name: page-lifecycle
description: 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

```bash
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

```bash
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

```bash
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

```bash
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](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:

```bash
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.