seedproject-web/AGENTS.md

# AGENTS.md — SeedProject base

This repository is a **cloneable website foundation** (the "SeedProject base"). If you
are reading this, someone cloned it to build a **new site**. Your job on a fresh clone
is to configure it for this specific site, then build it.

## First run — set up this clone

1. **Configure identity** (interactive):
   ```bash
   ./scripts/new-site.sh
   ```
   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 (**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:**
   ```bash
   cd app && npm install && npm run build     # outputs to ../public
   ```

3. **(Optional) set up the backend** — see [Backend](#backend-api).

That is the entire "spin up a new site" flow. Everything below is context for working
on the site afterward.

## The golden rule: one identity source

`site.config.json` (repo root) is the **single source of truth** for site identity —
name, URL, description, tagline, author, social, topic, audience, timezone.

- **Never hardcode** the site name, URL, author, or niche in components, pages, or engine
  configs.
- To change identity: edit `site.config.json`, then run `node scripts/configure.mjs`.
  That regenerates `app/src/config/site.json` (the theme reads it) and updates
  `agents/config.json` and `astroagent.config.json`.
- In the Astro theme, read identity from `SITE`, `authors`, etc. exported by
  `app/src/lib/blog-data.js` (which imports `app/src/config/site.json`).

## Structure

| Path | What it is |
|------|-----------|
| `site.config.json` | **The one file you edit** — site identity |
| `scripts/new-site.sh` | Fresh-clone setup (prompts → configure) |
| `scripts/configure.mjs` | Stamp `site.config.json` into every engine |
| `app/` | Astro frontend ("theme"). Build → `../public`. See `app/AGENTS.md` for coding standards. |
| `api/` | SeedProject PHP backend, served at `/api` (see below) |
| `agents/` | LLM agents: orchestrators + prompts + config. Catalog: `agents/AGENTS.md` (generated) |
| `public/` | Build output (git-ignored) |

## Backend (`api/`)

The PHP backend is served at `/api` on the same domain; the static frontend calls it
same-origin (`fetch("/api/...")`). Setup:

```bash
cd api && composer install
php console app:install --db-host=localhost --db-name=NAME --db-user=USER --db-pass=PASS \
  --url=<site-url> --name="<Site Name>"
php console db:migrate --status
```

- `php console app:install` writes `api/config.php` (git-ignored), imports the schema,
  and runs migrations.
- Endpoints: `GET /api/health` (public), `GET /api/admin/ping` (bearer `ADMIN_TOKEN`).
- New schema: add `api/db/migrations/NNN_name.sql`, apply with `php console db:migrate`.
- Web-server setup (aliasing `/api` → `api/` with PHP-FPM + front-controller rewrite):
  see `api/.memory/foundation.md`.

## Content pipeline & authoring

- `agents/` runs the autonomous content system. Each agent script carries an
  `@agent-manifest` header (class, trigger, model, prompts, skills, tools, tables);
  `node agents/catalog.mjs` regenerates the catalog (`agents/AGENTS.md` +
  `agents/agents.json` — the machine manifest a clone can diff to find missing deps).
  `configure.mjs` stamps the site name/topic/audience/author into `agents/config.json`
  and regenerates the catalog; 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 (`agents/prompts/*.system.md`, `agents/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) AND the whole pipeline is **JSON-file-based** (`config.json`, `calendar.json`,
  the `*-queue`/`*-scan` files, `state/`, `drafts/`). It is **slated for a DB-managed
  rewrite** (that state moves into MySQL via the `/api` backend). **Do NOT invest in
  genericizing the current JSON pipeline** — genericize the prompts as part of the DB
  rewrite. Treat the pipeline as niche-specific placeholder scaffolding until then.

## Guardrails

- **Never commit secrets.** `**/.env`, `api/config.php`, `api/system/.installed` are
  git-ignored — keep it that way. Dependencies (`node_modules/`, `api/vendor/`) and
  build output (`public/`) are git-ignored too and are installed/generated per clone.
- Keep the theme reusable and identity config-driven (see the golden rule).
- Verify any change still builds: `cd app && npm run build`.

## More

- Human quick-start: `README.md`
- Backend design + implementation plan: `api/.memory/foundation.md`,
  `api/.memory/foundation-plan.md`