docs: fix accuracy findings in deployment, usage, auth-flow (v0.9.0 audit)

[ajianaz]

What

Second chunk of the v0.9.0 docs accuracy audit (first chunk: #243).

docs/deployment.md

• .env examples: $(openssl rand -hex ...) replaced with literal placeholders + generate instructions (Compose does not evaluate command substitution); both keys standardized on hex 32
• chmod 777 data → chmod 755 + chown guidance for the container's titen user (UID from Dockerfile)
• Caddyfile: header_up sub-directives moved inside the reverse_proxy block (they were invalid outside it)
• systemd example: secrets moved to a root-only EnvironmentFile= (unit files are world-readable); TITEN_ENCRYPTION_KEY added (checklist marks it mandatory)
• Health checks standardized to /api/health; compose deployments verify via the web proxy on :3000 (API is not host-exposed), native/systemd on :7845
• All container references match docker-compose.yml (titen → titen-api)
• Backup/restore commands aligned with the ./data bind mount (was targeting a named volume titen_titen-data that compose does not create)
• Media storage clarified: local storage works out of the box (/data/media); S3 is optional

docs/usage.md

• Stray curl VIDEO example removed from the "Via CLI" section (the CLI has no video flags; the "Via API" section already documents VIDEO)
• TITEN_URL annotated: it is the CLI's API base URL (titen-core config ENV_URL), distinct from APP_URL (public site URL) — the scan's "inconsistency" is actually two different vars
• MCP tools table rebuilt from crates/titen-mcp/src/main.rs tools_list(): 29 tools (was: heading said 14, table listed 13, several names stale — get_account, get_post_analytics do not exist)

docs/auth-flow.md

• Authorize URL now documents all 8 scopes requested by the app (matches settings.rs authorize_url construction)

docs/architecture.md

• MCP tool count 14 → 29 (carry-over missed by docs: fix accuracy findings in README, architecture, AGENT, CONTRIBUTING (v0.9.0 audit) #243)

Why

Completes the documentation accuracy findings from the v0.9.0 cora scan. Deployment docs that reference a volume compose never creates, invalid Caddyfile syntax, and world-readable secrets in systemd units would actively mislead self-hosters.

Testing

• awk 'NR>=138' crates/titen-mcp/src/main.rs | grep -cE '"name": "[a-z_]+"' → 29
• grep -n "scope=" crates/titen-api/src/routes/settings.rs → 8-scope authorize URL
• grep -n "container_name\|expose:" docker-compose.yml → titen-web/titen-api, API expose: 7845 (not host-published)
• grep -n "TITEN_LOCAL_STORAGE_DIR" crates/titen-core/src/storage.rs → LocalStorage is a full backend; USER titen in Dockerfile → chmod/chown guidance
• grep -n "ENV_URL" crates/titen-core/src/config.rs → TITEN_URL is the CLI var
• grep -rn "video" crates/titen-cli/src/commands/post.rs → no video support in CLI
• Docs-only change: no build required

[github-actions]

🔍 Cora AI Code Review

✅ No issues found. Code looks good!

---

Review powered by cora-code · BYOK · MIT