# 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: 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
  `content-pipeline/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) |
| `content-pipeline/` | Autonomous content engine (research → write → review → publish) |
| `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

- `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.
- **astroagent** is the in-site authoring console; its identity is in
  `astroagent.config.json`.

## 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`