Summary
Prune redundant, superseded, or internal-only documentation so the repo has a clear, maintainable docs surface.
Current state
Documentation is split across several trees:
| Location |
Purpose |
docs/site/ |
Public Mintlify docs (integrations, guides, reference) — published at authsome.ai/docs |
docs/guides/ |
Repo-local guides (e.g. self-hosting.md) |
docs/adr/ |
Architecture decision records |
docs/internal/ |
Internal design docs (authsome-design.md, cli-design-review.md, manual-testing.md) |
docs/refactor.md |
Historical storage/identity refactor plan — largely shipped |
CONTEXT.md, docs/UBIQUITOUS_LANGUAGE.md |
Domain vocabulary for contributors/agents |
AGENTS.md, CONTRIBUTING.md, README.md |
Contributor and user entry points |
Candidates for removal or consolidation
docs/refactor.md: Marked as historical; phases 1–8 largely shipped. Content overlaps with CONTEXT.md and ADRs.
docs/internal/authsome-design.md: Canonical v1 design doc — may duplicate docs/site/concepts/architecture.mdx and CONTEXT.md.
docs/internal/cli-design-review.md, docs/internal/manual-testing.md: Internal-only; evaluate whether still referenced.
- Overlap between
docs/site/ and repo-root guides: e.g. self-hosting exists in docs/guides/ but not clearly linked from site docs.
- Stale terminology: Some docs may still reference retired concepts (per
CONTEXT.md flagged ambiguities).
Proposed work
Do not remove without review
docs/adr/* — keep unless explicitly superseded by a newer ADR.
CONTEXT.md, docs/UBIQUITOUS_LANGUAGE.md — active agent/contributor context.
docs/agents/* — issue tracker and triage conventions.
Acceptance criteria
- No duplicate canonical explanations of the same concept in conflicting places.
- Clear rule: public user docs in
docs/site/, contributor/domain docs at repo root, ADRs for decisions.
- Broken links from README, AGENTS.md, and site nav are fixed or removed.
Summary
Prune redundant, superseded, or internal-only documentation so the repo has a clear, maintainable docs surface.
Current state
Documentation is split across several trees:
docs/site/docs/guides/self-hosting.md)docs/adr/docs/internal/authsome-design.md,cli-design-review.md,manual-testing.md)docs/refactor.mdCONTEXT.md,docs/UBIQUITOUS_LANGUAGE.mdAGENTS.md,CONTRIBUTING.md,README.mdCandidates for removal or consolidation
docs/refactor.md: Marked as historical; phases 1–8 largely shipped. Content overlaps withCONTEXT.mdand ADRs.docs/internal/authsome-design.md: Canonical v1 design doc — may duplicatedocs/site/concepts/architecture.mdxandCONTEXT.md.docs/internal/cli-design-review.md,docs/internal/manual-testing.md: Internal-only; evaluate whether still referenced.docs/site/and repo-root guides: e.g. self-hosting exists indocs/guides/but not clearly linked from site docs.CONTEXT.mdflagged ambiguities).Proposed work
docs/files for duplication againstdocs/site/andCONTEXT.md.docs/site/docs.json/ navigation if pages are removed or merged.AGENTS.mdand contributor pointers reference only canonical docs.Do not remove without review
docs/adr/*— keep unless explicitly superseded by a newer ADR.CONTEXT.md,docs/UBIQUITOUS_LANGUAGE.md— active agent/contributor context.docs/agents/*— issue tracker and triage conventions.Acceptance criteria
docs/site/, contributor/domain docs at repo root, ADRs for decisions.