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

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

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