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):

   ./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:

   cd app && npm install && npm run build     # outputs to ../public
   

3. (Optional) set up the backend — see Backend.

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:

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