docs: consolidate and de-clutter the documentation tree (#306 )

CLAUDE.md rewritten (708 -> ~320 lines): four overlapping release
sections collapsed to one, stale v1->v35 schema history dropped (it
lives in CHANGELOG), marketplace endpoint internals and verbose
process sections moved out or tightened.

New focused docs:
- docs/RELEASING.md - release process, deploy workflows, CI quirks
  (RELEASE_TEMPLATE.md folded in as an appendix)
- docs/marketplace.md - marketplace ingestion + re-serving internals
- docs/README.md - documentation index by audience, linked from
  README.md and CLAUDE.md

Archived under docs/archive/: docs/superpowers/ (52 historical
planning artifacts), HACKATHON.md, pd-ps-comments.md,
security-audit-2026-04.md, future/NOTIFICATIONS.md.

Removed the docs/auto-install.md stub. Fixed dangling links in
connectors/jira/README.md and dev_docs/README.md, repointed
code/doc references to archived paths.

2026-05-14 18:54:22 +00:00

4.7 KiB

Raw Blame History

Agnes documentation

Index of all documentation, organized by who needs it. New here? Start with the row that matches your role.

You are…	Start with
Analyst — using Agnes to query data	`QUICKSTART.md`, then `HOWTO/`
Operator — deploying & running an instance	`PLATFORM_SETUP.md`
Developer — working on Agnes itself	`../ARCHITECTURE.md` + `architecture.md`

For analysts

Using the platform to analyze data.

QUICKSTART.md — local setup + first sync
HOWTO/ — task-oriented cookbook (querying, snapshots, common workflows)
DATA_SOURCES.md — data source connectors (Keboola, BigQuery, CSV) and how tables surface
metrics/ — canonical business-metric definitions (YAML)
HEADLESS_USAGE.md — PAT auth for CI / headless clients

For operators

Deploying, configuring, and running an Agnes instance.

PLATFORM_SETUP.md — the consolidated operator playbook (bootstrap, TLS, marketplaces, scheduler, telemetry)
ONBOARDING.md — end-to-end Terraform deployment into a new GCP project
DEPLOYMENT.md — picks between the Terraform and Docker Compose paths
CONFIGURATION.md — instance.yaml, env vars, per-instance options
state-dir.md — persistent data layout (data + state tiers, mount layouts, migration)
RBAC.md — access control: groups, members, resource grants
auth-google-oauth.md — Google OAuth setup + operator gotchas
auth-groups.md — Google Workspace group sync
admin/query-modes.md — table registration query modes
agent-setup-prompt.md — customize the /setup page banner
agent-workspace-prompt.md — customize the generated analyst CLAUDE.md
initial-workspace-override.md — per-instance analyst-workspace skeleton override
curated-marketplace-format.md — authoring marketplace-metadata.json for curated marketplaces
observability.md — PostHog integration (exceptions, tracing, session replay)
operator/news-content-guide.md — editorial guidelines for in-app news content

For developers

Working on the Agnes codebase.

../ARCHITECTURE.md — high-level system overview (the summary)
architecture.md — detailed architecture reference (module map, extract.duckdb contract, components)
../CLAUDE.md — project instructions for AI agents working in this repo
development.md — logging, request correlation, debug toolbar
local-development.md — LOCAL_DEV_MODE setup (what's mocked vs. real)
RELEASING.md — release process, deploy workflows, CI quirks
RELEASE_CHECKLIST.md — pre-merge checks for bootstrap-path changes
testing/ — test plans (clean-analyst bootstrap, VM test)
marketplace.md — Claude Code marketplace ingestion + re-serving internals
STORE_GUARDRAILS.md — flea-market upload guardrails (static checks + LLM review)
corporate-memory-governance.md — knowledge-distribution governance design
ADR-corporate-memory-v1.md — ADR: corporate-memory v1 decisions
llm-routing.md — design: provider-agnostic LLM routing
sample-data.md — sample data generator (e-commerce schema, size presets)
theme-reference.html — web UI theme/color reference
../dev_docs/ — server/developer-internal docs (not synced to analyst machines): server ops, disaster recovery, security audit, desktop app, design system, Telegram bot

Code-adjacent READMEs: ../connectors/jira/README.md, ../services/corporate_memory/README.md, ../scripts/README.md. Agent skill files: ../cli/skills/.

Other

../CHANGELOG.md — full change history (Keep-a-Changelog format)
archive/ — historical planning artifacts and superseded docs; not maintained, see archive/README.md

4.7 KiB Raw Blame History