From 0acc80f8e4b4bc77f1d1bf490c27838862695faa Mon Sep 17 00:00:00 2001 From: Carlos Arias Date: Sat, 4 Jul 2026 23:33:50 +0000 Subject: [PATCH] docs: add root AGENTS.md + CLAUDE.md for fresh-clone agents; fix agentUser leftover - AGENTS.md / CLAUDE.md: tell any agent (Claude Code, astroagent, Codex) what the base is and the exact fresh-clone setup flow (new-site.sh / configure.mjs / build) - configure.mjs: stamp astroagent ai.agentUser as -agent (was stale 'comiida-agent') Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01SYHWLHihq3v9nxNwoPCKSn --- AGENTS.md | 92 ++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 20 +++++++++ astroagent.config.json | 2 +- scripts/configure.mjs | 1 + 4 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7b79b47 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,92 @@ +# 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= --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` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..73204b5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,20 @@ +# CLAUDE.md + +Full agent instructions live in **[AGENTS.md](AGENTS.md)** — read that first. + +## Quick reference + +This is the **SeedProject base** — a cloneable Astro + PHP website foundation. On a +fresh clone, set it up for the new site: + +```bash +./scripts/new-site.sh # configure identity (prompts) → stamps engines +cd app && npm install && npm run build # build the frontend → ../public +``` + +- **Identity source of truth:** `site.config.json`. Edit it, then run + `node scripts/configure.mjs`. Never hardcode site name / URL / author elsewhere. +- **Backend:** `cd api && composer install && php console app:install --db-... --url=... --name=...` + (served at `/api`; see `api/.memory/foundation.md`). +- **Never commit secrets:** `**/.env`, `api/config.php` are git-ignored — keep it so. +- **Verify changes build:** `cd app && npm run build`. diff --git a/astroagent.config.json b/astroagent.config.json index 87bfa83..9f46827 100644 --- a/astroagent.config.json +++ b/astroagent.config.json @@ -13,7 +13,7 @@ "model": "claude-sonnet-4-6", "tools": "Read Write Edit Glob Grep WebSearch", "confine": true, - "agentUser": "comiida-agent", + "agentUser": "seedproject-site-agent", "skills": [ "brand", "ui-ux", diff --git a/scripts/configure.mjs b/scripts/configure.mjs index 12da949..9498854 100755 --- a/scripts/configure.mjs +++ b/scripts/configure.mjs @@ -53,6 +53,7 @@ if (existsSync(resolve(root, "astroagent.config.json"))) { const aa = read("astroagent.config.json"); aa.name = slug(site.name); aa.url = site.url; + if (aa.ai) aa.ai.agentUser = `${slug(site.name)}-agent`; write("astroagent.config.json", aa); }