docs: address reviewer feedback from issues #208-#215

[Vraj1234]

📄 Description

Resolves all eight sub-issues raised by external reviewer mglbleta in issue #207
(Docs Improvements/Questions for UW-SSEC team).

Each change was reviewed against the original reviewer question to ensure the
response is complete, accurate, and directly answers what was asked. A
devil's-advocate pass was done before implementation to ensure coverage ≥ 90%
per issue. See supporting_files/docs-improvement.md for the full per-issue
breakdown including issue comments.

Note: This PR intentionally does not modify docs/api/index.md or
mkdocs.yml — those files are already updated by PR #204 (static API
reference), which is currently in review.

#208 — API Reference Docs (docs/api/datamodels.md, docs/api/pipeline.md)

Added a "How to use this page" section to both auto-generated API reference
pages:

• datamodels.md: explains who the page is for (developers querying/extending
  models), clarifies it is not the HTTP REST API reference, and adds a
  15-item table of contents linking to every domain section so readers can
  navigate without scrolling the entire auto-generated output.
• pipeline.md: explains this is the programmatic Python package API (not HTTP
  endpoints), and why it lives under "API Reference" rather than the pipeline
  workflow guides.

#209 — CONTRIBUTING.md

Two fixes:

1. Pixi environment table: replaced the outdated two-item list (default,
   gis) with a complete table of all 9 current environments from pixi.toml
   — default, py312, py313, gis, etl, webservice, frontend,
   docs, deployment — each with a one-line purpose description.
2. Test command description: corrected the claim that pixi run test runs
   python -m pytest -ra --cov=ca_biositing. It actually runs
   python -m pytest tests/ --verbose (verbose output, no coverage). Added a
   pointer to pixi run test-cov for coverage reports.

Decision on the "self-contained vs. link-out" question: keeping CONTRIBUTING.md
self-contained — it is meant to be a one-stop guide for new contributors.

#210 — docs/webservice/README.md

Added an Authentication section below the API Overview table covering:

• Why POST is used for /v1/auth/token (credentials in request body, not
  URL, to stay out of server logs and browser history)
• What JWT means (JSON Web Token — compact, cryptographically signed,
  encodes identity)
• How to use the token after receiving it (Authorization: Bearer <token>)
• Token lifecycle: time-limited, no server-side session state

#211 — docs/datamodels/SQL_FIRST_WORKFLOW.md

Expanded the pgschema install section from macOS-only to four options:

• macOS: Homebrew (unchanged)
• Linux: pre-built binary from GitHub releases, chmod +x, move to
  /usr/local/bin/
• Windows: .exe binary from GitHub releases; noted as best-effort
  (workflow primarily tested on macOS/Linux)
• Cross-platform: pixi run install-pgschema — simplest option on
  macOS/Linux

#212 — docs/pipeline/ALEMBIC_WORKFLOW.md

Two improvements:

1. Clarified "manual" terminology: rewrote the section intro to name three
   concrete scenarios where autogenerate cannot help — (1) materialized views
   (CREATE MATERIALIZED VIEW is invisible to Alembic autogenerate),
   (2) data migrations (transforming existing row values requires custom Python
   logic), (3) downgrades (rolling back is always manual).
2. DATABASE_URL alternatives: updated both command blocks (manual revision
   • downgrade) to show export DATABASE_URL=... once in the shell session as
     a cleaner alternative to the inline prefix on every command.

#213 — Pipeline Overview (comment only, no file changes)

The docker-compose exec app alembic upgrade head command referenced in the
issue no longer exists in src/ca_biositing/pipeline/README.md — it was
already removed in a prior commit. Resolved with an issue comment confirming
pixi run migrate is equivalent and preferred.

#214 — docs/architecture.md

Rewrote four sections as reality-based prose, removing aspirational bullet
lists that described unimplemented capabilities:

• Deployment & Operations: Docker Compose orchestration, Alembic as sole
  schema source of truth, Prefect UI + /v1/health for observability. Removed:
  Kubernetes, automated backups, centralised logging.
• Security Considerations: JWT auth flow and Google Cloud service account
  credentials. Removed: rate limiting, audit logging, data anonymisation, RBAC.
• Scalability & Performance: PostGIS + materialised views, Uvicorn async,
  pagination, Prefect retry. Removed: Redis, unimplemented connection pooling,
  multi-region.
• Future Architecture Considerations: three prose sections (Service
  Decomposition, Cloud-Native Migration, Analytical Query Layer) each explaining
  the trigger condition and noting how the current structure already makes the
  transition tractable — rather than listing technology names as bullets.

#215 — README.md / docs/README.md

Reordered the ETL pipeline quick-start block so pixi run migrate is explicit
step 3 (before pixi run run-etl as step 4). Added an inline comment
clarifying that start-services already applies migrations automatically via
the setup-db container at startup — pixi run migrate is for pulling new
migration files without restarting services.

---

✅ Checklist

• I ran pre-commit run --all-files and all checks pass
• Tests added/updated where needed
• Docs added/updated if applicable
• I have linked the issue this PR closes (if any)

🔗 Related Issues

Resolves #208
Resolves #209
Resolves #210
Resolves #211
Resolves #212
Resolves #213
Resolves #214
Resolves #215
References #207

💡 Type of change

Type	Checked?
🐞 Bug fix	[ ]
✨ New feature	[ ]
📝 Documentation	[x]
♻️ Refactor	[ ]
🛠️ Build/CI	[ ]
Other (explain)	[ ]

🧪 How to test

1. Run pixi run -e docs docs-serve and verify the site builds without errors.
2. Navigate to API Reference → Datamodels — confirm the "How to use this
   page" intro and 15-item TOC appear above the auto-generated content.
3. Navigate to API Reference → Pipeline — confirm the intro section
   explains the programmatic vs. HTTP API distinction.
4. Navigate to Contributing — confirm the pixi environment table lists all
   9 environments and the test command description matches pixi run test.
5. Navigate to Webservice → Overview — confirm the Authentication section
   appears below the API Overview table.
6. Navigate to Datamodels → SQL-First Workflow — confirm Linux, Windows,
   and pixi install options appear under Prerequisites.
7. Navigate to Pipeline → Alembic Workflow — confirm the Manual Migration
   section lists three concrete scenarios and the DATABASE_URL blocks show the
   export alternative.
8. Navigate to Home — confirm pixi run migrate appears as step 3 before
   pixi run run-etl in the quick-start block.
9. Navigate to Architecture — confirm Deployment, Security, Scalability,
   and Future Architecture sections are prose paragraphs, not bullet lists.

📝 Notes to reviewers

• This PR deliberately avoids docs/api/index.md and mkdocs.yml — both are
  already modified by PR Docs/changelog and static api reference #204 (static API reference page, currently in review).
  Merging this PR before Docs/changelog and static api reference #204 is safe; merging Docs/changelog and static api reference #204 after will add to the
  existing API Reference nav without conflict.
• Issue [Docs]: pipeline / overview #213 required no file changes — a comment was posted directly on the
  issue explaining that the referenced outdated command was already removed and
  confirming pixi run migrate is the preferred approach.
• All issue comments (drafted in supporting_files/docs-improvement.md) should
  be posted on [Docs]: API Reference Docs #208–[Docs]: Home / Overview #215 after this PR merges.

[read-the-docs-community]

Documentation build overview

📚 ca-biositing | 🛠️ Build #32246099 | 📁 Comparing 872f05a against latest (66cb070)

  🔍 Preview build  

Show files changed (16 files in total): 📝 16 modified | ➕ 0 added | ➖ 0 deleted

File	Status
index.html	📝 modified
CODE_OF_CONDUCT/index.html	📝 modified
CONTRIBUTING/index.html	📝 modified
architecture/index.html	📝 modified
notebook_setup/index.html	📝 modified
webservice/index.html	📝 modified
api/datamodels/index.html	📝 modified
api/pipeline/index.html	📝 modified
datamodels/SCHEMA_DRIFT/index.html	📝 modified
datamodels/SQL_FIRST_WORKFLOW/index.html	📝 modified
pipeline/ALEMBIC_WORKFLOW/index.html	📝 modified
pipeline/DOCKER_WORKFLOW/index.html	📝 modified
pipeline/ETL_WORKFLOW/index.html	📝 modified
pipeline/GCP_SETUP/index.html	📝 modified
pipeline/PREFECT_WORKFLOW/index.html	📝 modified
pipeline/USDA/ANALYTICS_HANDOFF/index.html	📝 modified