Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions SWEEP.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,20 @@

The docs state facts that other people's work changes: the API, the MCP server, the SDKs, the schema, the tools. Two habits keep them true.

**1. Docs follow what ships, the same hour.** When something the docs describe ships, its owner tells the docs' maintainer (Kael) with the commit; the page changes and deploys that hour, not at the next sweep. What counts: a new or changed route, field, error code or limit (keel); a new schema-dist serial; a new SDK, Python, Unity or Atlas version; a changed tool, link or name. The generated parts follow on their own (element tables from schema-dist at each build, error codes from keel's list, the TypeScript reference from the pinned SDK); the hand-written pages are the ones that need a person. A new keel error code is the exception that needs both: `node scripts/gen_errors.mjs --refresh` and its `### <code>` section the same hour, because keel's `doc_url` already points at that anchor (every 410 linked to a missing `#gone` until docs-next 12e90a0, 2026-10-18; CI only warns). A changed palette in keel's `worlds/public_page.py` is followed the same way: `node scripts/gen_palettes.mjs --refresh`, then the build; keel is private, so CI never sees it, and the sweep's check 2b reads it only on a machine with keel's checkout. A keel route added, removed or given other credentials is followed with `node scripts/gen_callers.mjs --refresh` the same hour: `npm run verify` prints STALE when the credentials figure's snapshot differs from the live API document, and the sweep's check 2c fails on it. A change to Sign in with OnlyWorlds (the authorize page's parameters, the token route's fields or answer, the code's lifetime) is followed with `node scripts/gen_signin.mjs --refresh`: verify prints STALE for the sign-in figure's snapshot, and the sweep's check 2d fails on it and on the document disagreeing with keel's code. A change to the world's time fields (a new schema-dist serial that renames or retypes one, the API's World schema, the spelling of now) or to the demo world's line is followed with `node scripts/gen_time.mjs --refresh`: verify prints STALE for the time figure's snapshot, and the sweep's check 2e fails on it. A change to what the public reader leaves out (a new removal, a mark renamed), to the `/w/` routes, the graph's leave-outs or the two `404` pages is followed with `node scripts/gen_public.mjs --refresh`: keel is private, so CI never sees it, and the sweep's check 2f fails on it; the figure's keyless routes follow the credentials snapshot. A change to what an element write takes (a base field, a cap, a key tolerated or refused, the extension prefixes or their cap, a category's own fields) is followed with `node scripts/gen_write.mjs --refresh`: verify prints STALE for the write body figure's snapshot, and the sweep's check 2g fails on it. A change to the draught's route (a section added, renamed or turned on or off by default, what the budget never cuts, a policy parameter, its values or default, a packet key) is followed with `node scripts/gen_draught.mjs --refresh`: verify prints STALE for the draught figure's snapshot, and the sweep's check 2h fails on it. A change to proposals (a state, a proposal route, who may call it, its answers or refusals, the expiry's range or default, the review's decisions, the queue's states or kinds, which writes the switch turns into proposals) is followed with `node scripts/gen_proposals.mjs --refresh`: verify prints STALE for the proposals figure's snapshot, and the sweep's check 2i fails on it. The same commit adds the change's dated line to `/docs/changelog` (one entry stood for 161 commits until docs-next 1879d09, 2026-10-20). **Every change to the server that is not internal is followed within a day of its merge**: a dated line in `changelog.md` for what it moved, and a record in the maintainer's follow log either way, including "no docs change" when the docs describe nothing it moved. The server's repository is private, so the changelog names what changed, never the change's number there. The marker is what Boss's weekly reader checks against keel's merged PRs (2026-10-20); it stays a comment, hidden on the page and visible in the page's Markdown copy. Commit subjects stay free.
**1. Docs follow what ships, the same hour.** When something the docs describe ships, its owner tells the docs' maintainer (Kael) with the commit; the page changes and deploys that hour, not at the next sweep. What counts: a new or changed route, field, error code or limit (keel); a new schema-dist serial; a new SDK, Python, Unity or Atlas version; a changed tool, link or name. The generated parts follow on their own (element tables from schema-dist at each build, error codes from keel's list, the TypeScript reference from the pinned SDK); the hand-written pages are the ones that need a person. A new keel error code is the exception that needs both: `node scripts/gen_errors.mjs --refresh` and its `### <code>` section the same hour, because keel's `doc_url` already points at that anchor (every 410 linked to a missing `#gone` until docs-next 12e90a0, 2026-10-18; CI only warns). A changed palette in keel's `worlds/public_page.py` is followed the same way: `node scripts/gen_palettes.mjs --refresh`, then the build; keel is private, so CI never sees it, and the sweep's check 2b reads it only on a machine with keel's checkout. A keel route added, removed or given other credentials is followed with `node scripts/gen_callers.mjs --refresh` the same hour: `npm run verify` prints STALE when the credentials figure's snapshot differs from the live API document, and the sweep's check 2c fails on it. A change to Sign in with OnlyWorlds (the authorize page's parameters, the token route's fields or answer, the code's lifetime) is followed with `node scripts/gen_signin.mjs --refresh`: verify prints STALE for the sign-in figure's snapshot, and the sweep's check 2d fails on it and on the document disagreeing with keel's code. A change to the world's time fields (a new schema-dist serial that renames or retypes one, the API's World schema, the spelling of now) or to the demo world's line is followed with `node scripts/gen_time.mjs --refresh`: verify prints STALE for the time figure's snapshot, and the sweep's check 2e fails on it. A change to what the public reader leaves out (a new removal, a mark renamed), to the `/w/` routes, the graph's leave-outs or the two `404` pages is followed with `node scripts/gen_public.mjs --refresh`: keel is private, so CI never sees it, and the sweep's check 2f fails on it; the figure's keyless routes follow the credentials snapshot. A change to what an element write takes (a base field, a cap, a key tolerated or refused, the extension prefixes or their cap, an element type's own fields) is followed with `node scripts/gen_write.mjs --refresh`: verify prints STALE for the write body figure's snapshot, and the sweep's check 2g fails on it. A change to the draught's route (a section added, renamed or turned on or off by default, what the budget never cuts, a policy parameter, its values or default, a packet key) is followed with `node scripts/gen_draught.mjs --refresh`: verify prints STALE for the draught figure's snapshot, and the sweep's check 2h fails on it. A change to proposals (a state, a proposal route, who may call it, its answers or refusals, the expiry's range or default, the review's decisions, the queue's states or kinds, which writes the switch turns into proposals) is followed with `node scripts/gen_proposals.mjs --refresh`: verify prints STALE for the proposals figure's snapshot, and the sweep's check 2i fails on it. The same commit adds the change's dated line to `/docs/changelog` (one entry stood for 161 commits until docs-next 1879d09, 2026-10-20). **Every change to the server that is not internal is followed within a day of its merge**: a dated line in `changelog.md` for what it moved, and a record in the maintainer's follow log either way, including "no docs change" when the docs describe nothing it moved. The server's repository is private, so the changelog names what changed, never the change's number there. The marker is what Boss's weekly reader checks against keel's merged PRs (2026-10-20); it stays a comment, hidden on the page and visible in the page's Markdown copy. Commit subjects stay free.

**2. A sweep every week**, because the first habit misses what nobody thought to mention. `node scripts/sweep.mjs` does the measurable part and lists what moved; a person reads the rest. A status check marks the sweep overdue by itself after two weeks without a run. The cadence can slacken once the docs stop moving fast.

## The procedure

1. **Run it.** `node scripts/sweep.mjs` (add `--no-links` for a quick one). Fix every STALE it prints: bump a pin, refresh a snapshot, mend a link, replace a word, follow a release (a changelog line that links its page and names its version, a serial by its number, or `<!-- <repo> <tag>: no docs change -->` when it moved no claim).
2. **Read MOVED against the pages that state it.** Each commit line names a source; the page to read is:
- keel: `docs/development/api-reference.mdx`, `api/*` (reads, writes, links, changes, errors, images, members, cors), `mcp.md`, `agents.md`, the error table, `schema/worlds.md`, `lenses/api.md`
- schema-dist: `schema/*`, `schema/conventions.mdx`, the profile pages `schema/profiles.md` and `schema/profiles/*`, the lens pages `lenses.mdx` and `lenses/graph.md`; the element tables regenerate on their own
- keel: `docs/development/api-reference.mdx`, `api/*` (reads, writes, links, changes, errors, images, members, cors, lenses, draught), `mcp.md`, `agents.md`, the error table, `schema/worlds.md`, the draught's concept page `world-graph/draught.md`
- schema-dist: `schema/*`, `schema/conventions.mdx`, the profile pages `schema/profiles.md` and `schema/profiles/*`, the World graph pages `world-graph.md`, `lenses.mdx` and `lenses/graph.md`; the element tables regenerate on their own
- `@onlyworlds/sdk`: `typescript.md`, `packages.md`; its README is the repo's, kept in step by hand
- the Python package: `python.md`; Atlas: `tools/atlas.md`, `getting-started/*`; Unity: `unity.md`, `games.md`; Obsidian: `tools/obsidian-plugin.md`
- A link that sends the reader elsewhere for a claim: open the target and find the claim there. The link check sees that the page exists, not what it says (agents.md sent readers to Writes for the agent mark, which Writes never mentioned, 2026-10-18).
3. **Read for language** (Titus's two standing complaints, 2026-10-09): OnlyWorlds explained again where a page has no need to; the 22 categories listed again; words that are not OnlyWorlds elements (a faction, an item, a realm) used as if they were. `sweep.mjs` names the pages that restate the 22 and flags the words it knows.
3. **Read for language** (Titus's two standing complaints, 2026-10-09): OnlyWorlds explained again where a page has no need to; the 22 element types listed again; words that are not OnlyWorlds elements (a faction, an item, a realm) used as if they were. `sweep.mjs` names the pages that restate the 22 and flags the words it knows.
Every page is edited here (since 2026-10-18, Titus's word: the content lane is Kael's whole; Skeld's content folder no longer syncs). Skeld brings facts: a keel change that moves a page's claim comes to the docs' maintainer the hour it ships, and the page follows that hour.
4. **Run `npm run build && npm run verify`,** push, check the deploy. A code block that was added or changed is run as extracted from the page source, never retyped: a Write example run from my own script passed while the page's copy lacked its import (2026-10-18).
5. **Walk the living map of sharing** (the maintainer's map of every sharing route, kept outside this repository; its check runs with `--write`). A DRIFT (a row names a route keel no longer has) is fixed in the map's `rows.json` before the stamp. Its findings (a sharing route with no row, a route nothing classifies, a row with no walk or no control, a walk older than two weeks) are the sweep's walking list: re-walk what the docs' pages lean on, and route the rest to the row's owner.
Expand All @@ -26,5 +26,5 @@ The docs state facts that other people's work changes: the API, the MCP server,
## The terms (one place)

- **"the standard"** names the thing, for people. **"schema"** only for the files (`schema/*.yaml`, schema-dist) and the reference pages about them.
- Elements are the 22 categories: Character, Creature, Species, Family, Collective, Institution, Location, Object, Construct, Ability, Trait, Title, Language, Law, Event, Narrative, Phenomenon, Relation, Map, Pin, Marker, Zone. A game's own words go on the left of a mapping table, never in prose as if they were ours.
- Elements are of the 22 element types, the one public word for them (never categories; `verify-public-words.mjs` fails on the word in built prose): Character, Creature, Species, Family, Collective, Institution, Location, Object, Construct, Ability, Trait, Title, Language, Law, Event, Narrative, Phenomenon, Relation, Map, Pin, Marker, Zone. A game's own words go on the left of a mapping table, never in prose as if they were ours.
- The Python package is on PyPI since 2026-10-11: `pip install onlyworlds`. The old install line from GitHub (`git+https://…/python-sdk`) is a sweep check.
89 changes: 46 additions & 43 deletions astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -77,42 +77,45 @@ export default defineConfig({
{ slug: 'docs/schema/profiles/addresses' },
],
},
{ slug: 'docs/schema/example' },
{
label: 'Element types',
collapsed: true,
items: [{ autogenerate: { directory: 'docs/schema/element_categories' } }],
},
{ slug: 'docs/schema/example' },
],
},
{
label: 'Lenses',
// the world read as a graph: the concept pages; the lens and draught routes stay under API
label: 'World graph',
items: [
{ slug: 'docs/lenses', label: 'Overview' },
{ slug: 'docs/world-graph', label: 'Overview' },
{ slug: 'docs/lenses' },
{ slug: 'docs/world-graph/draught' },
{ slug: 'docs/lenses/graph' },
{ slug: 'docs/lenses/api', label: 'On the API' },
],
},
{
label: 'API',
label: 'Tools',
items: [
{ slug: 'docs/development/api-reference', label: 'Overview' },
{ slug: 'docs/development/api/reads' },
{ slug: 'docs/development/api/links' },
{ slug: 'docs/development/api/writes' },
{ slug: 'docs/development/api/changes' },
{ slug: 'docs/development/api/members' },
{ slug: 'docs/development/api/hidden' },
{ slug: 'docs/development/api/public' },
{ slug: 'docs/development/api/proposals' },
{ slug: 'docs/development/api/draught' },
{ slug: 'docs/development/api/signin' },
{ slug: 'docs/development/api/images' },
{ slug: 'docs/development/api/files' },
{ slug: 'docs/development/api/cors' },
{ slug: 'docs/development/api/classic' },
{ slug: 'api/errors' },
{ label: 'Interactive reference', link: 'https://www.onlyworlds.com/api/docs' },
{ slug: 'docs/tools', label: 'Overview' },
{ slug: 'docs/tools/atlas' },
{ slug: 'docs/tools/lantern' },
{ slug: 'docs/tools/obsidian-plugin' },
{ slug: 'docs/tools/onlyworlds-com' },
{ slug: 'docs/tools/explorer' },
{ slug: 'docs/tools/council' },
{ slug: 'docs/tools/legacy' },
],
},
{
label: 'AI agents',
items: [
{ slug: 'docs/development/ai', label: 'Overview' },
{ slug: 'docs/development/mcp' },
{ slug: 'docs/development/agents' },
{ slug: 'docs/development/llm-guide' },
{ slug: 'docs/development/toolkit' },
],
},
{
Expand All @@ -133,26 +136,26 @@ export default defineConfig({
],
},
{
label: 'AI agents',
items: [
{ slug: 'docs/development/ai', label: 'Overview' },
{ slug: 'docs/development/mcp' },
{ slug: 'docs/development/agents' },
{ slug: 'docs/development/llm-guide' },
{ slug: 'docs/development/toolkit' },
],
},
{
label: 'Tools',
label: 'API',
items: [
{ slug: 'docs/tools', label: 'Overview' },
{ slug: 'docs/tools/atlas' },
{ slug: 'docs/tools/lantern' },
{ slug: 'docs/tools/obsidian-plugin' },
{ slug: 'docs/tools/onlyworlds-com' },
{ slug: 'docs/tools/explorer' },
{ slug: 'docs/tools/council' },
{ slug: 'docs/tools/legacy' },
{ slug: 'docs/development/api-reference', label: 'Overview' },
{ slug: 'docs/development/api/reads' },
{ slug: 'docs/development/api/links' },
{ slug: 'docs/development/api/writes' },
{ slug: 'docs/development/api/changes' },
{ slug: 'docs/development/api/members' },
{ slug: 'docs/development/api/hidden' },
{ slug: 'docs/development/api/public' },
{ slug: 'docs/development/api/proposals' },
{ slug: 'docs/development/api/draught' },
{ slug: 'docs/development/api/lenses', label: 'Lenses' },
{ slug: 'docs/development/api/signin' },
{ slug: 'docs/development/api/images' },
{ slug: 'docs/development/api/files' },
{ slug: 'docs/development/api/cors' },
{ slug: 'docs/development/api/classic' },
{ slug: 'api/errors' },
{ label: 'Interactive reference', link: 'https://www.onlyworlds.com/api/docs' },
],
},
{
Expand Down Expand Up @@ -185,9 +188,9 @@ export default defineConfig({
'- [OpenAPI document](https://www.onlyworlds.com/api/v2/openapi.json): the API, machine-readable',
].join('\n'),
customSets: [
{ label: 'API', description: 'the REST API v2: reads, links, writes, changes, members, hidden elements, public worlds and keyless reads, images, files, CORS, v1 migration and errors', paths: ['docs/development/api-reference', 'docs/development/api/**', 'api/errors', 'docs/getting-started/keys'] },
{ label: 'API', description: 'the REST API v2: reads, links, writes, changes, members, hidden elements, public worlds and keyless reads, proposals, the draught, lenses, images, files, CORS, v1 migration and errors', paths: ['docs/development/api-reference', 'docs/development/api/**', 'api/errors', 'docs/getting-started/keys'] },
{ label: 'Schema', description: 'the 22 element types, their fields, the conventions for using them and the extension profiles', paths: ['docs/schema/**', 'docs/schema'] },
{ label: 'Lenses', description: 'the lens profile: a saved way of reading a world, a world read as a graph, and the lens routes on the API', paths: ['docs/lenses', 'docs/lenses/**'] },
{ label: 'World graph', description: "a world read as a graph: lenses (the lens profile, a saved way of reading a world), the draught (one Character's reading in one call) and the graph itself; the lens and draught routes are in the API set", paths: ['docs/world-graph', 'docs/world-graph/**', 'docs/lenses', 'docs/lenses/**'] },
{ label: 'AI agents', description: 'the MCP server, agent seats, the LLM guide and the toolkit', paths: ['docs/development/ai', 'docs/development/mcp', 'docs/development/agents', 'docs/development/llm-guide', 'docs/development/toolkit'] },
],
// llms-small keeps asides and line breaks: the reader found notes like "no delete tool, by design" dropped
Expand Down
Loading
Loading