docs: remove maintainer-only content, duplicates and unbacked claims - #104
Merged
Conversation
Delete capabilities/agent-forge (a vendored AI-agent skill library used only by the maintainer), ROADMAP.md, TASKS.md, SPEC.md and DECISIONS.md (internal planning scaffolds, two of them with unclosed code fences), and the root docs/ directory, which was an older copy of the docs-site guides that the README still linked to. The release runbook and the rulesets how-to move to the maintainer handbook. AGENTS.md is now self-contained, ARCHITECTURE.md describes only files that exist and absorbs the two ADRs, CONTRIBUTING.md no longer promises a monthly discussion thread that never happened, and CHANGELOG.md carries the 0.3.0 release date. The README documentation table points at the docs-site sources so it works before the site opens.
- Drop the screenshots checklist, the empty Slack section, the Looker 'questions to resolve' and the three placeholder blog posts; the blog is unlinked until there is a post with content. - Rewrite the roadmap: serve, interactive charts and the Looker guide had already shipped; three items were internal chores. - Stop documenting toolbar.actions: the loader validates it but the template never reads it, so the 'show only one action' example did nothing. The example dashboards drop the key too. - Embedded analytics now documents only the bundle.json contract; the @glyf/client and @glyf/react packages do not exist yet. - Product analytics shows the real dashboards/product.yml; the previous copy called activation_health(0.82), which raises against the macro's keyword-only signature. - Merge guides/configuration into the reference page (adding the undocumented execution.backend key and the svg/png-only rule), fold existing-dbt-project into the quickstart it duplicated, and collapse the three AI-context pages into one. - Cut the macro chapter duplicated between the dashboard YAML and macros guides, which also un-nests 'Custom macros' from under 'Theme'. - Rewrite llms.txt around glyf build / glyf serve and the current page set. - Carry over three sentences from the deleted root docs tree.
This was referenced Aug 29, 2026
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.
A review of everything user-facing in the repository, with three goals: remove content that only the maintainer needs, remove filler, and remove claims that the code does not back.
Removed from the repository
capabilities/agent-forge/(37 files) — a vendored AI-agent skill library. Maintainer tooling; it lives in its own repository.ROADMAP.md,TASKS.md,SPEC.md,DECISIONS.md— internal planning scaffolds.TASKS.mdandSPEC.mdhad unclosed code fences;ROADMAP.mdproposedglyf serveas future work. The two ADRs inDECISIONS.mdnow live inARCHITECTURE.md.docs/— an older, diverged copy of the docs-site guides. The README table now links the docs-site sources on GitHub, so the guides stay reachable before the site opens. Four sentences that existed only indocs/were carried across.docs/release.mdand the rulesets how-to — maintainer procedure, relocated out of the public repo.examples/screenshots.md— an asset-capture checklist.Claims corrected
toolbar.actionswas documented with a "show only one action" example. The loader validates the key buttoolbar.j2never reads it, so the example did nothing. Removed from the docs and from the example dashboards. (The key is still accepted, so existing YAML keeps working — worth a follow-up to either wire it or drop it.)npm install @glyf/client @glyf/reactand theGlyfProviderexample — these packages do not exist. The page now documents the realbundle.jsoncontract and points the JavaScript packages at the roadmap.activation_health(0.82)in the product-analytics page raisesTypeError(the macro's parameters are keyword-only). The page now shows the shippedproduct.yml.serve, interactive charts and the Looker guide as planned; all three ship.CONTRIBUTING.mdpromised "an active discussion thread every month"; there has been one welcome thread since May.ARCHITECTURE.mddescribed theme files and a token JSON that do not exist.Consolidated
guides/configuration→reference/configuration(one page, now also documentingexecution.backendand thatrender.formatsaccepts onlysvg/png).get-started/existing-dbt-project→get-started/quickstart(70% identical).llms.txtrewritten: its "core workflow" omittedglyf buildandglyf serve.Checks
npm run buildindocs-site/passes withonBrokenLinks: 'throw'.uv run pytest: 115 passed.