diff --git a/AGENTS.md b/AGENTS.md
index 7b79b47..b661840 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,8 @@ is to configure it for this specific site, then build it.
    ```
    It prompts for the site name, URL, description, author, etc., writes them to
    `site.config.json`, and stamps them across every engine.
-   Non-interactive alternative: edit `site.config.json` by hand, then run
+   Non-interactive alternative (**use this if you are an autonomous agent** — the script
+   above prompts and will block): edit `site.config.json` by hand, then run
    `node scripts/configure.mjs`.
 
 2. **Build the frontend:**
@@ -71,11 +72,38 @@ php console db:migrate --status
 
 ## Content pipeline & authoring
 
-- `content-pipeline/` runs the autonomous content system, driven by
-  `content-pipeline/config.json` (populated by `configure.mjs`). Runtime state
-  (`drafts/`, `state/`, `logs/`) is git-ignored and regenerates per site.
+- `content-pipeline/` runs the autonomous content system. `configure.mjs` stamps the
+  site name/topic/audience/author into `content-pipeline/config.json`, and its runtime
+  state (`drafts/`, `state/`, `logs/`) is git-ignored and regenerates per site.
+- **⚠️ NOT yet niche-generic — do not trust the pipeline output as-is.** The prompts and
+  some scripts (`content-pipeline/prompts/*.system.md`, `content-pipeline/scripts/*.mjs`)
+  still contain wording from the original site (a Medellín restaurant publication) and do
+  **not** read the niche from config. Running the pipeline before genericizing it will
+  produce off-niche content. Fix: make those files read `config.site.{name,topic,audience}`.
+  See [Status & known gaps](#status--known-gaps).
 - **astroagent** is the in-site authoring console; its identity is in
   `astroagent.config.json`.
+- To add a post by hand: create `app/src/content/blog/<slug>/index.mdx` following the
+  schema in `app/src/content.config.js` (copy the sample `welcome` post as a template).
+
+## Local development
+
+- **Frontend:** `cd app && npm run dev` (Astro dev server) — enough for theme/content work.
+- **The `/api` backend does NOT work under `astro dev`.** It needs a real web server
+  (Apache/nginx + PHP-FPM) with `/api` aliased to `api/`, plus `php console app:install`.
+  The `/api-health-test` page therefore only returns data on a deployed instance, not in dev.
+
+## Status & known gaps
+
+Read this before relying on any subsystem:
+
+- ✅ **Frontend theme** — fully config-driven; `npm run build` produces a clean site.
+- ✅ **Setup** — `new-site.sh` / `configure.mjs` work.
+- ⚠️ **`/api` Foundation** — code is written and code-verified (composer, `php console`,
+  autoload, graceful CLI failures), but the **live DB + HTTP round-trip is UNVERIFIED**
+  (never run on a served instance with a real database).
+- ⚠️ **Content pipeline** — prompts/scripts are **still niche-specific** (Medellín
+  restaurants); genericize them to `config.site.*` before use.
 
 ## Guardrails