Reorganizing at Scale

First-round titles tend to be abstract, and the first directory structure is rarely ideal. Once the knowledge base has reached a useful size, the Agent can survey what is already approved and propose a more readable, direct structure — and at that point its proposal is better than anything possible during planning, because the content exists. Apply it, then observe for another round. Reorganizing is a series of revisions, far cheaper than producing again.

Survey the approved knowledge and propose a more direct directory and title
structure. Show me the before/after, then revise once I confirm.

Pick the lightest tool

flowchart TB
  q{"What needs to change?"} -->|menu titles, order, grouping| map["Adjust the knowledge map<br/>no prose rewritten"]
  q -->|a page's location| move["revise --move-to<br/>same identity, links updated"]
  q -->|content boundaries| split["Split or merge<br/>new and revision tasks"]
  split --> retire["Retire obsolete pages<br/>after destinations are approved"]

Change	Tool	What stays
Rename a directory, reorder, regroup, place a page in a second location	Knowledge-map adjustment	Article identity, URL and prose
Move a page to another path	context revise <page> --move-to <path>	Identity and section IDs; incoming Markdown links are updated on approval
Split one page, or merge several	Ordinary new and revision tasks	Useful detail, until its destination is approved
Remove pages now covered elsewhere	context task retire	Sources and shared assets

Knowledge-map adjustments

The knowledge map controls the website navigation and the LLM Docs organization together. Ask in conversation to move a topic, rename a directory, change the order or organize the same articles for another reader task; this works during production or after it, without recapturing sources. Each entry keeps a stable key, so a renamed menu needs no new article and moving a menu entry does not change the article URL.

Prefer, in this order: revise an existing article, add a page to a matching category, add a coherent child category. A top-level addition, rename or removal is proposed with a before/after tree and needs your explicit approval.

Splits and merges

The Agent reads the affected pages and current sources before deciding what to keep, deepen, split, merge or retire. Destination content is approved first; only then are the original page and its incoming links revised. Useful conditions, steps and explanations must have a destination before anything is removed — omitting a page in Review rejects the candidate, it does not retire the approved article.

Retiring pages

reason: These reader tasks are now covered by the approved guide.
targets:
  - path: architecture/old-guide.md
    replacement: sop/current-guide.md

context task retire --input <file> previews the retirement; it does not go through the HTML Review, and once you have approved the deletion the Agent applies the returned command without asking again. Retirement removes the Markdown and structure entries together, points incoming page links at the replacement, and returns a restore input for rollback. Links into a specific paragraph of a split page are repaired first, because the CLI cannot infer where a paragraph went.

Pages with continuing value — such as documentation for an older version — normally stay. A shorter new text or a changed menu is not a reason to retire.

Make the new structure stick

Before delivery, check that each page sits under its main reader task, titles match bodies, siblings are ordered deliberately and no directory is empty or an accidental duplicate. Record the lasting intent of each category briefly in the AGENTS.md of the Context knowledge workspace, so later updates place new pages the same way.

大规模重组

第一轮的标题往往偏抽象，最初的目录结构也很少是理想的。当知识库达到可用的规模后，Agent 可以梳理已批准的内容，提出一个更易读、更直接的结构——此时它的方案会优于规划阶段能做到的任何方案，因为内容已经存在。落实之后，再观察一轮。重组是一系列修订，成本远低于重新生产。

Survey the approved knowledge and propose a more direct directory and title
structure. Show me the before/after, then revise once I confirm.

选择最轻量的工具

flowchart TB
  q{"需要改变什么？"} -->|菜单标题、顺序、分组| map["调整知识地图<br/>不重写正文"]
  q -->|页面位置| move["revise --move-to<br/>身份不变，链接同步更新"]
  q -->|内容边界| split["拆分或合并<br/>新增任务和修订任务"]
  split --> retire["下线过时页面<br/>在目标页面批准之后"]

变更	工具	保持不变的内容
重命名目录、调整顺序、重新分组、把页面放到第二个位置	知识地图调整	文章身份、URL 和正文
把页面移动到其他路径	context revise <page> --move-to <path>	身份和章节 ID；指向它的 Markdown 链接在批准时更新
拆分一个页面，或合并多个页面	普通的新增任务和修订任务	有用的细节，直到其目标位置获得批准
删除已在别处覆盖的页面	context task retire	来源和共享资产

知识地图调整

知识地图同时控制网站导航和 LLM Docs 的组织方式。在对话中提出即可：移动某个主题、重命名目录、调整顺序，或为另一种读者任务重新组织同一批文章；这在生产过程中或之后都可以进行，无需重新采集来源。每个条目都有一个稳定的键，因此重命名菜单不需要新文章，移动菜单条目也不会改变文章 URL。

优先顺序如下：修订现有文章，把页面加入匹配的分类，新增一个内容连贯的子分类。顶级的新增、重命名或删除会附带变更前后的目录树作为提案，并需要你明确批准。

拆分与合并

Agent 会先阅读受影响的页面和当前来源，再决定哪些保留、深化、拆分、合并或下线。目标内容先获得批准；之后才会修订原页面及指向它的链接。有用的条件、步骤和解释在删除任何内容之前都必须有去处——在审核中略去某个页面只会拒绝该候选，并不会下线已批准的文章。

下线页面

reason: These reader tasks are now covered by the approved guide.
targets:
  - path: architecture/old-guide.md
    replacement: sop/current-guide.md

context task retire --input <file> 会预览下线操作；它不经过 HTML 审核，一旦你批准了删除，Agent 就会直接执行返回的命令，不再询问。下线会同时删除 Markdown 和结构条目，把指向该页面的链接改指向替代页面，并返回一份用于回滚的恢复输入。指向被拆分页面中某个具体段落的链接会先行修复，因为 CLI 无法推断某个段落去了哪里。

具有持续价值的页面——例如旧版本的文档——通常会保留。新文本更短或菜单有变化，都不是下线的理由。

让新结构保持下去

交付前，请检查每个页面都位于其主要读者任务之下、标题与正文相符、同级页面的顺序经过斟酌，且没有空目录或意外重复的目录。在 Context 知识工作区的 AGENTS.md 中简要记录每个分类的长期意图，以便后续更新以同样的方式放置新页面。