Files
skillshare/wiki/ai-context.md
T
Willie 9c048ac7ac fix(ui): show where pull conflict versions differ (#331)
* fix(ui): show where pull conflict versions differ

The pull conflict dialog showed both versions in short 208px panes with no
marking, so users had to scroll and compare long files by eye to find what
actually conflicted.

Panes now use 55vh, lines that only one side has are tinted, each side
scrolls to its first difference, and the header counts differing lines.

* chore(docs): move ai-context router config into wiki/

The router config describes wiki topics, so it belongs next to the pages it
maps; docs/ reads as public documentation. The script is synced with the
upstream router, which also normalizes backslash paths and forces UTF-8
output for Windows consoles.

The router runs on the host rather than the devcontainer, so the kernel now
says to use py or python on Windows when python3 is unavailable.

* fix(ui): give pull conflict panes room and tidy the dialog edges

Short conflicting files still rendered as cramped strips, so panes now keep
a 40vh minimum. A long body scrolled straight under the title, so the header
gets a separator like the footer. The conflict banner's text sat above its
button because notes align to the top for multi-line errors; it is centered
when the message is the fixed conflict text.

* fix(ui): bound the pull conflict line diff

diffLines keeps an n×m table, so two 16 KiB previews that differ on every
line could allocate hundreds of megabytes and freeze the dialog. Matching
leading and trailing lines are now skipped before diffing, and versions whose
differing middle would still need over a million cells are shown unmarked.
2026-10-02 18:40:40 +08:00

3.1 KiB

AI Context Router

This page is the complete in-repository manual for maintaining agent documentation routing without an external skill. Load it with python3 scripts/ai-context.py ai-context.

Layers

  1. Kernel: root AGENTS.md, loaded for every task. It contains only universal rules and topic triggers.
  2. Scoped instructions: package- or app-specific nested AGENTS.md files. Every scoped file must be loaded by at least one topic.
  3. Topics: wiki/ai-context.json maps topics to complete files or exact headings. scripts/ai-context.py <topic> prints only those sections.
  4. History: wiki/history/ stores milestone logs in their original language. History is not loaded by default and is indexed in wiki/README.md.

wiki/ai-context.json is the single source of truth. The tables in AGENTS.md and wiki/README.md are discovery mirrors.

When Documentation Must Change

Update documentation in the same change that makes it stale:

Change Update
Changed behavior described by a topic That topic page
Found documentation that contradicts code Verify the code, fix the documentation, and mention it in the handoff
Learned a cross-task lesson from a failure A one-line behavior rule in the kernel plus the procedure in its topic
Finished a milestone wiki/history/<milestone>.md and the wiki/README.md history index
Added a recurring kind of task A new topic, JSON entry, and both topic tables
Added a nested AGENTS.md Map it to a topic

Do not put volatile state in the wiki, including progress counts, current owners, or today's blocker. Keep that information in the tracker.

Adding or Changing a Topic

  1. Put the content in wiki/<page>.md. A topic should represent a recognizable kind of work, not one ticket or file.
  2. Map it in wiki/ai-context.json using a complete file or exact heading.
  3. Add it to the tables in AGENTS.md and wiki/README.md.
  4. Run python3 scripts/ai-context.py check.
  5. Render the topic and read it as an agent would; it must be sufficient on its own for the task.

Heading references must be unique and exact. A section ends at the next heading of the same or higher level. Never use line ranges.

What Check Enforces

  • Every path stays inside the repository and exists, and every heading matches exactly once.
  • AGENTS.md and every topic stay within byte budgets. Split an over-budget topic instead of raising its cap.
  • Every JSON topic appears in AGENTS.md.
  • There are no orphans:
    • every non-history wiki page is loaded by a topic;
    • every history file is indexed in wiki/README.md;
    • every nested AGENTS.md is loaded by a topic.

Only genuine human-only exceptions belong in the JSON unrouted map, and every exception requires a reason.

Skills and CI

Skills retain workflow phases, report templates, and helper invocation. They load the applicable topic before acting; repository rules must not exist only in a skill.

The router check runs through the Makefile docs-check/check targets and the test and website workflows. After changing the router, run:

python3 scripts/ai-context.py check