Repository navigation
[Docs] A front page and a first-run path for readers new to Strata - #1
Merged
Merged
Conversation
rwkeyes
force-pushed
the
docs/newcomer-onboarding
branch
3 times, most recently
from
November 13, 2026 16:48
452eba1 to
1f3867a
Compare
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
force-pushed
the
docs/newcomer-onboarding
branch
from
November 13, 2026 16:55
1f3867a to
2a14284
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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,specandTUNEwere used everywhere and defined nowhere.Two other things were wrong on the way in:
docs/README.md,INSTALL.md,SOURCE_INSTALL.mdandAI_SETUP.mdall said version 0.2.5 on a treethat is 0.2.12, and eight pages told the reader to look for
Strata-0.2.9-*.exeinstallers. The releasepage 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.mdlinked the suite result todirigo-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.mdis rewritten rather than patched, because its structure (fork evidence first) was the problem: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;
is the single fact that decides whether the rest of the page is worth reading;
--version— "a build of some other tree is not evidence you have this one" is now the stated check;DIRIGO.mdforthe measurements, which stay where they are.
New pages:
docs/GETTING-STARTED.md— two routes (released install; this snapshot from source), every step paired witha 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:
Strata-<version>-…and a note that the releasepage carries the version, so the instruction cannot go stale again;
docs/README.mdgains a start-here block, a "this fork" section and a rule against hard-coding versions ininstructions;
docs/UPSTREAM-README.md— its 60 local references were written for the repository root and were dead fromdocs/; 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 notshipped;
dirigo-results/community-report/README.md— one link was written for thebench/results/<run>/depth andwas one
../short after the folder moved underdirigo-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-verifiedstill reproduces the deployedtree hash recorded in
DIRIGO.md.Validation
Passed:
DIRIGO.md,AGENTS.md,CONTRIBUTING.md,SECURITY.md,docs/*.mdfor 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 indirigo-results/community-report/), and the 229 that remainare inside historical
bench/results/(124) andapps/host/docs/(104) evidence folders plus one indirigo-results/, and were left alone deliberately.flags referenced, 39 found in
src/,sycl/src/,serve/; the only miss isgit clone --branch.strata-device --list-devices,/v1/models,/v1/tuningand thedata/expert-profile.binrequirement wereeach confirmed in the tree.
#anchorin the new pages was matched against a heading in its target page."Measured on" label; tables were checked for ragged columns.
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.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 touser-content-…, so a cross-page#quantizationlink would have been dead.Failed:
none observed.
Not run:
the ones already recorded as verified in
DIRIGO.md(SYCL AOTbmg-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.
Limits
routed to their own build pages instead of being given an untested command.
docs/INSTALL.mdand the other upstream guides still describe upstream's app/Terminal product, whose versionnumbering moves independently of this snapshot. Generalising the file names removes the rot; the pages will
still want a refresh when upstream renames something.
bench/results/andapps/host/docs/are historical evidence and stay dead onpurpose. Fixing them would rewrite other people's measurement records.