torbenandClaude Opus 5.5
4ec22d376d
Files changed: - CHANGES.md - README.md - VERSION - instructions/kb-profiles.md - instructions/link-taxonomy.md - instructions/page-lifecycle.md - instructions/wiki-ingest/SKILL.md - instructions/wiki-lint/SKILL.md - kb/entities/COLLECTION.md - kb/entities/INDEX.md - kb/entities/organizations/E3DC GmbH.md - kb/entities/people/E3DC GmbH.md - kb/index.md - kb/log.md - tools/CONTRACT.md - tools/chemenu/commands/lint.py - tools/chemenu/kb_scan.py - tools/chemenu/lint_core.py - tools/chemenu/tests/test_lint.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/tests/test_types_cmd.py - types/entity.md - types/entity.organization.md - types/entity.person.md - types/entity.schema.yaml Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
160 lines
6.9 KiB
Markdown
160 lines
6.9 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: page-lifecycle
|
|
description: 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.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [Rename](#rename)
|
|
- [Delete](#delete)
|
|
- [Move](#move)
|
|
- [Promote a section to its own page](#promote-a-section-to-its-own-page)
|
|
- [Drop a single reference](#drop-a-single-reference)
|
|
- [Afterwards](#afterwards)
|
|
- [Scope](#scope)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## 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:`.
|
|
|
|
`--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
|
|
|
|
```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 - 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```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`,
|
|
`--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:
|
|
|
|
```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.
|