Carlos Arias
0acc80f8e4
- 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 <slug>-agent (was stale 'comiida-agent') Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SYHWLHihq3v9nxNwoPCKSn
92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
# 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`
|