Why
An external Deep Research report about Freeshard (run by a partner in Gemini, 2026-09-12) invented a substantial part of what it asserted about us: a .freeshard.io domain shape, a "Freeshard Time-Series DB", scale-to-zero VMs with multi-second cold starts as the platform's gravest risk, and family accounts as a shipped feature. None of that is in any of our sources; it was reconstructed from the public web because there was no authoritative one to read.
We already solved this problem once, for app developers: digest.md at the repo root is an AI-optimized digest of the developer docs, fetched by the add-app skill in app-repository instead of crawling the site. The pattern works. It is scoped to app development only, and it is stale: Generated: 2026-06-29, regenerated by hand via .claude/skills/generate-digest/, wired into nothing.
What to do
1. Split the digest along the sections the docs already have.
docs/overview/ (product and concepts) and docs/developer_docs/ (building apps) are two different readers with two different questions. One digest serving both is why the product side is thin today.
digest-product.md — what a shard is, the vocabulary (shard, terminal, app, portal network, controller), single-user isolation, what the platform does for an app owner.digest-developer.md — the current digest.md content: compose template, app_meta.json, routing and access control, persistence, lifecycle, submission, revenue share.
Back-compat: the add-app skill in app-repository fetches digest.md by name. Either keep that filename for the developer digest or update the consumer in the same change; do not leave it fetching a file that no longer exists.
2. Write "What Freeshard is not" as a docs page, and let the digest generate from it.
The load-bearing part, and the one no documentation site writes: state plainly what Freeshard is not, and what is not shipped yet. No multi-tenant database, no household or family accounts today (tracked in FreeshardBase/freeshard#141), no central store of owners' app data, and the precise shape of renting versus self-hosting, since a first draft of llms.txt got that one wrong in the other direction. Keep the existing status: upcoming / status: disabled convention for features documented but unavailable, and state no dates.
It belongs in docs/overview/ as a real page, not only inside a digest. Two reasons. Humans want it: it is what a prospective owner reads before the pricing page, and it is the honest version of the comparison table already on the overview page. And it is the only way the sentence exists once. Today that material is written by hand in two places, llms.txt and the private fact map in FreeshardBase/ai-company, which is a second source of truth for facts that will drift. With a docs page as the home, the product digest generates from it and llms.txt links it.
Add it to nav in mkdocs.yml under Overview.
3. Extend the repo skill to regenerate both digests.
.claude/skills/generate-digest/ currently rewrites one file. It should produce both, from their respective source directories, and stamp each with a Generated: date.
4. Enforce freshness in CI.
A workflow that fails when a docs section changed in a PR without its digest being regenerated in the same PR. Compare the changed paths under docs/overview/ and docs/developer_docs/ against changes to the corresponding digest file. This repo is public, so Actions minutes are free here.
A date comparison alone is not enough: it passes as long as someone touched the digest, for any reason. Path-to-path is the check with teeth.
Out of scope
Publishing the digests at stable URLs on docs.freeshard.net, and the llms.txt entry point on freeshard.net that will point at them, are handled separately.
Why
An external Deep Research report about Freeshard (run by a partner in Gemini, 2026-09-12) invented a substantial part of what it asserted about us: a
.freeshard.iodomain shape, a "Freeshard Time-Series DB", scale-to-zero VMs with multi-second cold starts as the platform's gravest risk, and family accounts as a shipped feature. None of that is in any of our sources; it was reconstructed from the public web because there was no authoritative one to read.We already solved this problem once, for app developers:
digest.mdat the repo root is an AI-optimized digest of the developer docs, fetched by theadd-appskill in app-repository instead of crawling the site. The pattern works. It is scoped to app development only, and it is stale:Generated: 2026-06-29, regenerated by hand via.claude/skills/generate-digest/, wired into nothing.What to do
1. Split the digest along the sections the docs already have.
docs/overview/(product and concepts) anddocs/developer_docs/(building apps) are two different readers with two different questions. One digest serving both is why the product side is thin today.digest-product.md— what a shard is, the vocabulary (shard, terminal, app, portal network, controller), single-user isolation, what the platform does for an app owner.digest-developer.md— the currentdigest.mdcontent: compose template,app_meta.json, routing and access control, persistence, lifecycle, submission, revenue share.Back-compat: the
add-appskill in app-repository fetchesdigest.mdby name. Either keep that filename for the developer digest or update the consumer in the same change; do not leave it fetching a file that no longer exists.2. Write "What Freeshard is not" as a docs page, and let the digest generate from it.
The load-bearing part, and the one no documentation site writes: state plainly what Freeshard is not, and what is not shipped yet. No multi-tenant database, no household or family accounts today (tracked in FreeshardBase/freeshard#141), no central store of owners' app data, and the precise shape of renting versus self-hosting, since a first draft of
llms.txtgot that one wrong in the other direction. Keep the existingstatus: upcoming/status: disabledconvention for features documented but unavailable, and state no dates.It belongs in
docs/overview/as a real page, not only inside a digest. Two reasons. Humans want it: it is what a prospective owner reads before the pricing page, and it is the honest version of the comparison table already on the overview page. And it is the only way the sentence exists once. Today that material is written by hand in two places,llms.txtand the private fact map inFreeshardBase/ai-company, which is a second source of truth for facts that will drift. With a docs page as the home, the product digest generates from it andllms.txtlinks it.Add it to
navinmkdocs.ymlunder Overview.3. Extend the repo skill to regenerate both digests.
.claude/skills/generate-digest/currently rewrites one file. It should produce both, from their respective source directories, and stamp each with aGenerated:date.4. Enforce freshness in CI.
A workflow that fails when a docs section changed in a PR without its digest being regenerated in the same PR. Compare the changed paths under
docs/overview/anddocs/developer_docs/against changes to the corresponding digest file. This repo is public, so Actions minutes are free here.A date comparison alone is not enough: it passes as long as someone touched the digest, for any reason. Path-to-path is the check with teeth.
Out of scope
Publishing the digests at stable URLs on docs.freeshard.net, and the
llms.txtentry point on freeshard.net that will point at them, are handled separately.