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, timezone.

- **Never hardcode** the site name, URL, or author 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).
- 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) |
| `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`.

## Authoring content

- To add a post: 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).

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