Skip to content

docs: restructure six bloated pages and add a docs style guide - #1262

Merged
kvlonge merged 10 commits into
mainfrom
docs/semantic-compilation
Oct 27, 2026
Merged

kvlonge merged 10 commits into
mainfrom
docs/semantic-compilation

Conversation

@kvlonge

@kvlonge kvlonge commented Oct 27, 2026

Copy link
Copy Markdown
Contributor

Why

Several docs pages grew by appending a paragraph per feature or performance change. They mixed implementation detail (cache files, batching, storage internals) and history notes into user pages, with little structure, so they were hard to read.

Changes

  • Restructured six pages around what users do, with examples and tables: Semantic Compilation, sqb compile, Testing, sqb janitor, Recall and Project Configuration.
  • Removed internals users can't act on, history wording ("earlier releases", "as before", upgrade notes) and rules duplicated between pages (linked instead). Kept every flag, setting, default, limit, code and message.
  • Corrected the janitor's source-schema block to say it applies in direct mode.
  • Added website/STYLE.md, a short docs style guide, and an AGENTS.md section requiring docs changes to edit pages into shape rather than append.
  • Regenerated the skill reference copies of the changed pages.

Verification

  • Website build passes; every in-site anchor link resolves.
  • Each page reviewed against its previous version and, for changed claims, against the source.
  • Public-repository hygiene scan passes.

@kvlonge
kvlonge enabled auto-merge (squash) October 27, 2026 09:25
@kvlonge
kvlonge merged commit 8a1ec07 into main Oct 27, 2026
22 checks passed
@kvlonge
kvlonge deleted the docs/semantic-compilation branch October 27, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant