# Documentation proposal

## Problem

The project has no user-facing or developer-facing docs. Knowledge lives in `CLAUDE.md`
(written for AI context, not humans), scattered inline comments, and the code itself.
As the feature surface grows and more users join, we need:

- A guide for **users** (how to upload, sync, edit, manage privacy)
- A guide for **admins** (how to run an instance, manage users, reset passwords)
- An **API reference** (what endpoints exist, what they expect, what they return)
- A **developer guide** (how to run locally, architecture, how to contribute)

---

## Proposed structure

```
docs/
  index.md              Overview and quick links
  user-guide.md         End-user: upload, sync, edit, privacy, settings
  admin-guide.md        Admin: deploy, init, invite users, reset passwords, rebuild
  api.md                API reference (hand-written, augmented by OpenAPI)
  architecture.md       BAS schema, data flow, shard model, federation
  developer-guide.md    Local setup, how to run tests, how to contribute
```

`CLAUDE.md` stays as-is — it is AI context, not user docs. The two serve different
audiences and should not be merged.

---

## API documentation strategy

FastAPI auto-generates an OpenAPI 3.1 spec from the route decorators. It is already
served at `/api/docs` (Swagger UI) and `/api/redoc` (ReDoc) when the server is running.
Right now the auto-docs are sparse because:

- Most endpoints return bare `JSONResponse` instead of typed Pydantic response models
- Endpoint docstrings are minimal or absent
- Request bodies are raw `request.json()` instead of Pydantic models

### Recommended approach: two-layer docs

**Layer 1 — machine-readable (OpenAPI, auto-generated)**

Incrementally add Pydantic request/response models to the endpoints that matter most
(auth, activity CRUD, admin actions). FastAPI will pick them up automatically and the
Swagger UI becomes usable. No extra tooling needed.

Priority endpoints to type first:
- `POST /api/auth/login` / `logout` / `reset-password`
- `POST /api/register`
- `GET /api/me`
- `GET|POST /api/activity/{id}`
- `DELETE /api/activity/{id}`
- `POST /api/admin/users/{handle}/reset-password-code`
- `GET|POST /api/me/preferences` (once built)

**Layer 2 — human-readable (`docs/api.md`)**

A hand-written reference that groups endpoints by domain (auth, activities, admin,
sync), explains the overall auth model (cookie-based, httpOnly), rate limiting, and
covers things OpenAPI can't express well (SSE streams, error semantics, side effects
like rebuild triggers).

The OpenAPI spec and the hand-written doc are complementary, not duplicates:
OpenAPI is precise and machine-readable; `api.md` gives context and explains *why*.

---

## Tooling options

| Option | Pros | Cons |
|--------|------|------|
| Plain markdown in `docs/` | Zero tooling, lives in repo, renders on GitHub | No search, no versioning, no sidebar nav |
| MkDocs + Material theme | Beautiful, search, auto-nav from folder structure, can embed OpenAPI via plugins | Needs Python dep + build step; another thing to deploy |
| Docusaurus | Great for open-source projects, versioning, i18n | Node toolchain, heavier |
| VitePress | Fast, Vite-based (already in the stack), markdown + Vue | Still a separate site to host |
| Just the Swagger UI at `/api/docs` | Auto-generated, always up-to-date | Only covers the API, not user/admin/architecture |

**Recommendation:** Start with plain markdown in `docs/` — no build step, always
available, no new infrastructure. If the project goes public or the user base grows,
migrate to MkDocs Material (one `mkdocs.yml` + `pip install mkdocs-material`).

For the API specifically: enable the Swagger UI on the live server (currently it may
be disabled in production) so admins can explore it directly at `/api/docs`.

---

## Enabling Swagger UI in production

By default FastAPI serves `/docs` and `/redoc`. In `bincio serve`, the FastAPI app is
created with:

```python
app = FastAPI(docs_url=None, redoc_url=None)  # check current value
```

For a private instance (auth-walled), it is safe to expose `/api/docs` — add a note
in `admin-guide.md` that it exists. Alternatively, serve it only when an env var is set.

---

## Suggested first milestone

1. Create `docs/` with `index.md`, `admin-guide.md`, `api.md`
2. `admin-guide.md`: deploy, init, invite, password reset, rebuild, reset data
3. `api.md`: auth endpoints + activity endpoints, hand-written
4. Enable Swagger UI on the server (or at least document that it exists at `/api/docs`)
5. Add Pydantic models to the 8 priority endpoints above

Everything else (user guide, architecture, developer guide, MkDocs) is second milestone.