Skip to content

[Docs] A front page and a first-run path for readers new to Strata - #1

Merged
rwkeyes merged 1 commit into
dirigo/0.2.12-verifiedfrom
docs/newcomer-onboarding
Nov 13, 2026
Merged

rwkeyes merged 1 commit into
dirigo/0.2.12-verifiedfrom
docs/newcomer-onboarding

Conversation

@rwkeyes

@rwkeyes rwkeyes commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Problem and result

The repository's front page was written for someone who already knew Strata. Its first line named release
0.2.11 and its largest section was the fork's GuideLLM table, so a reader arriving from a search or a link
learned what this fork measured before learning what Strata is, what hardware it needs, or how to start it.
The guides behind it (81 pages) were accurate but had no entry point and no glossary: pack, shard,
IQ1_M, PLE, slot, spec and TUNE were used everywhere and defined nowhere.

Two other things were wrong on the way in:

  • docs/README.md, INSTALL.md, SOURCE_INSTALL.md and AI_SETUP.md all said version 0.2.5 on a tree
    that is 0.2.12, and eight pages told the reader to look for Strata-0.2.9-*.exe installers. The release
    page has carried 0.2.13 names since 2026-11-09, so a newcomer following the install steps could not find
    the file they were told to download.
  • DIRIGO.md linked the suite result to dirigo-results/unit-tests/, which is not in this repository.

After: the front page answers "what is this, can my PC run it, what do I do next" in that order, with a
five-row start-here table whose cost in time is stated; a guided walkthrough and a glossary exist; the
instructions no longer contain a version number that will rot.

Related discussion

none — documentation only, no behaviour, no interface, nothing to agree scope on.

Approach

README.md is rewritten rather than patched, because its structure (fork evidence first) was the problem:

  • what Strata is in plain words, and what this repository is — a fork of Niko1221/Strata, source only,
    whose default branch is the v0.2.12 verified snapshot (engine 0.1.58), pointing at upstream's release for
    anyone who wants to run rather than build;
  • hardware and memory before any download: the smallest recommended pack needs ~37.6 GB of RAM+VRAM, which
    is the single fact that decides whether the rest of the page is worth reading;
  • a quick start that builds this snapshot (SYCL AOT), builds the pack, serves it, and proves the binary with
    --version — "a build of some other tree is not evidence you have this one" is now the stated check;
  • the terms a newcomer meets, a first-run failure table, a repository map, and a pointer to DIRIGO.md for
    the measurements, which stay where they are.

New pages:

  • docs/GETTING-STARTED.md — two routes (released install; this snapshot from source), every step paired with
    a check that proves it worked, then model choice, connecting a coding tool, the slow-answer table and a
    "what working looks like" checklist.
  • docs/GLOSSARY.md — every term the guides use, grouped as model / engine / server+this-fork / measurement,
    written in plain language.

Quality control, same topic (the reader's path), kept in one commit:

  • version stamps and installer names corrected/generalised: Strata-<version>-… and a note that the release
    page carries the version, so the instruction cannot go stale again;
  • docs/README.md gains a start-here block, a "this fork" section and a rule against hard-coding versions in
    instructions;
  • docs/UPSTREAM-README.md — its 60 local references were written for the repository root and were dead from
    docs/; all now resolve. Prose untouched: it stays upstream's text, byte for byte otherwise;
  • DIRIGO.md — the suite row points at the record that carries the result and states that the raw log is not
    shipped;
  • dirigo-results/community-report/README.md — one link was written for the bench/results/<run>/ depth and
    was one ../ short after the folder moved under dirigo-results/.

Compatibility: documentation only. No source file, no flag, no default and no interface changed. The verified
snapshot is untouched — this is a separate branch, so dirigo/0.2.12-verified still reproduces the deployed
tree hash recorded in DIRIGO.md.

Validation

Passed:

  • Relative links. A resolver run over the 23 front-door files (root README, DIRIGO.md, AGENTS.md,
    CONTRIBUTING.md, SECURITY.md, docs/*.md for the install/getting-started/glossary/troubleshooting set,
    and the 7 translated READMEs): 0 broken relative references. Before this branch the tree had 260; this
    fixes 31 (30 in docs/UPSTREAM-README.md, 1 in dirigo-results/community-report/), and the 229 that remain
    are inside historical bench/results/ (124) and apps/host/docs/ (104) evidence folders plus one in
    dirigo-results/, and were left alone deliberately.
  • Commands. Every flag used on the new pages was checked against the parsers in this tree: 40 distinct
    flags referenced, 39 found in src/, sycl/src/, serve/; the only miss is git clone --branch.
    strata-device --list-devices, /v1/models, /v1/tuning and the data/expert-profile.bin requirement were
    each confirmed in the tree.
  • Anchors. Every cross-page #anchor in the new pages was matched against a heading in its target page.
  • House style. Every page has title / purpose / steps / details, and every measured figure carries a
    "Measured on" label; tables were checked for ragged columns.
  • Version strings. grep -rn 'version 0\.2\.5\|Strata-0\.2\.9-' now returns only the release notes,
    packaging/UPDATES.md (feed-tool examples) and the preserved upstream README.
  • Rendering. Both new pages were rendered through GitHub's Markdown API (POST /markdown, mode=gfm):
    README produces 9 headings, 6 tables and the centered screenshot intact; the glossary's tables survive the
    sanitiser. A manual <a id> anchor was dropped rather than relied on — GitHub rewrites such ids to
    user-content-…, so a cross-page #quantization link would have been dead.

Failed:

none observed.

Not run:

  • No build and no serve. This is a documentation change; the build and serve lines in the quick start are
    the ones already recorded as verified in DIRIGO.md (SYCL AOT bmg-g31, engine 0.1.58, 1,535 tests OK),
    not a new build on the box the pages were edited from. What stays unverified here is that a reader following
    the page on a clean machine hits no packaging surprise — the flags and paths are checked, the environment is
    not.
  • Not viewed in a browser: rendering was checked through GitHub's own Markdown API instead (see Passed).

Limits

  • The quick start is Intel/SYCL because that is what this branch verified; AMD, NVIDIA and Mac readers are
    routed to their own build pages instead of being given an untested command.
  • docs/INSTALL.md and the other upstream guides still describe upstream's app/Terminal product, whose version
    numbering moves independently of this snapshot. Generalising the file names removes the rot; the pages will
    still want a refresh when upstream renames something.
  • The 229 dead links inside bench/results/ and apps/host/docs/ are historical evidence and stay dead on
    purpose. Fixing them would rewrite other people's measurement records.

@rwkeyes
rwkeyes force-pushed the docs/newcomer-onboarding branch 3 times, most recently from 452eba1 to 1f3867a Compare November 13, 2026 16:48
The repository's front page described a 0.2.11 release and opened with
the fork's GuideLLM table, so a reader who had never run Strata learned
what the fork measured before learning what Strata is, what it needs, or
how to start it. The guides themselves were accurate but scattered across
81 pages with no glossary and no entry point.

Front page (README.md), rewritten:
- what Strata is in plain words, and what this repository is (a fork of
  Niko1221/Strata, source only, default branch = the v0.2.12 verified
  snapshot, engine 0.1.58)
- a start-here table with the five real paths and their cost in time
- hardware and memory stated before any download, not after
- a quick start that builds this snapshot, prepares a pack, serves it and
  proves the binary with --version; the flags are checked against the
  option parsers in this tree
- the terms a newcomer meets on the first day, a first-run failure table,
  a repository map, and a pointer to DIRIGO.md for the numbers

New pages:
- docs/GETTING-STARTED.md: two routes (released install, this snapshot),
  each step with a check that proves it worked, plus model choice,
  connecting a coding tool and the "is it working" checklist
- docs/GLOSSARY.md: every term the guides use, grouped by model / engine /
  server / measurement, in plain language

Quality control:
- docs/README.md: start-here block, this-fork section, glossary, and a
  rule not to hard-code a version number in an instruction
- the five pages that claimed "version 0.2.5" now name 0.2.12; the eight
  pages that named Strata-0.2.9-*.exe installers (which the release page
  has not carried since 0.2.9) now name the file by its release
- docs/UPSTREAM-README.md: relative links were written for the repository
  root and were dead at docs/; all 60 local references now resolve
- DIRIGO.md: the suite-log link pointed at a directory that is not in this
  repository; the row now points at the record that carries the result and
  says the raw log is not shipped
@rwkeyes
rwkeyes force-pushed the docs/newcomer-onboarding branch from 1f3867a to 2a14284 Compare November 13, 2026 16:55
@rwkeyes
rwkeyes merged commit 6577927 into dirigo/0.2.12-verified Nov 13, 2026
1 check passed
@rwkeyes
rwkeyes deleted the docs/newcomer-onboarding branch November 13, 2026 16:55
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