From 1e6329e85cf24c01d78d421b5a3e18b1675c7e7e Mon Sep 17 00:00:00 2001 From: Carlos Arias Date: Sat, 4 Jul 2026 23:38:29 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20make=20AGENTS.md=20honest=20=E2=80=94?= =?UTF-8?q?=20flag=20pipeline=20is=20not=20niche-generic,=20add=20local-de?= =?UTF-8?q?v=20+=20status/gaps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A cold-start agent reading the old text would wrongly trust the content pipeline as config-driven and generate off-niche content. Now states the real status: - content pipeline prompts/scripts are still Medellín-specific (not config-driven yet) - /api backend doesn't run under 'astro dev' (needs Apache/PHP-FPM + app:install) - /api Foundation is code-verified only; live DB/HTTP round-trip unverified - autonomous agents should use the non-interactive configure path (new-site.sh blocks) Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01SYHWLHihq3v9nxNwoPCKSn --- AGENTS.md | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) 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//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