# Lycato Documentation

> Operating knowledge base. Read like a senior engineer joining the team.

## Layout

```
docs/
  research/         market + tooling research notes (with citations)
  competitors/      direct + adjacent product analysis
  users/            pain points, personas, journeys, use cases
  strategy/         product, roadmap, pricing, growth
  architecture/     current-state snapshots + design decisions
  execution/        execution master plans, phase logs
  analytics/        KPIs, north-star definitions
  growth/           channel strategy, activation, retention
  security/         threat model, audits
  performance/      audits, budgets
  deployment/       release runbooks
  hosted/           hosted product: the shipped Firebase slice + the
                    container-per-tenant design that is still design
  testing/          test strategy + matrix
  decisions/        ADR log
  retrospectives/   per-phase retros
  demo/             demo scripts
  site/             docs site source
  superpowers/      historical specs + plans (immutable; kept for context)
  CHANGELOG.md      release log
```

## What of this is published

`pnpm docs:build` renders only `architecture/`, `blog/`, `brand/`,
`deployment/`, `hosted/`, `users/` and the five root files
`CHANGELOG.md` / `DESIGN_SYSTEM.md` / `README.md` / `status.md` / `leave.md` — the allowlist is
`PUBLIC_DOC_DIRS` / `PUBLIC_DOC_FILES` in `scripts/build-docs.mjs`. Every other
directory here is internal and is not emitted. Adding a directory to that
allowlist makes it world-readable on `lycato.app`.

## Reading order for a new contributor

Needs a repo checkout — four of the six are internal and are not on the
published site.

1. `architecture/CURRENT_STATE.md` — what exists today. (published)
2. `strategy/PRODUCT_STRATEGY.md` — the thesis. (repo only)
3. `users/USER_PAIN_POINTS.md` — what we're attacking. (published)
4. `competitors/FEATURE_MATRIX.md` — where we differ. (repo only)
5. `execution/EXECUTION_MASTER_PLAN.md` — what we're building next. (repo only)
6. `decisions/ADR_LOG.md` — why we made the calls we made. (repo only)

## Citation policy

External claims cite a URL inline. Internal claims point to a file path
or commit hash. No "studies show" or "it's known that" without a link.

## Update cadence

- `CURRENT_STATE.md` updated at each minor version cut.
- `CHANGELOG.md` updated per commit if user-visible.
- `ADR_LOG.md` updated when a non-trivial design call is made.
- Strategy docs reviewed each quarter or on a major pivot.