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

60 lines
3.1 KiB
Markdown

# 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:
```sh
python3 scripts/ai-context.py check
```