crearte-monorepo/AGENTS.md

AGENTS.md

Repository role

Monorepo wrapper for the crearte full stack. This repo tracks AGENTS.md, clone_all.sh, and docs/ (roadmap and all cross-repo design/plan docs). The three product repos are nested clones, each with its own git history and AGENTS.md:

crearte-monorepo/     # this repo (wrapper)
├── crearte/          # frontend (build context for web-* images)
├── crearte-server/   # backend Go API (build context for api-* images)
└── crearte-deploy/   # compose orchestration, no app code

Everything runs in containers. Do not introduce host-run workflows (no npm run dev / go run on the host) in docs, scripts, or compose.

Safety Rules

• Branch naming: {feat|fix|docs|chore}/{branch-name} (e.g. fix/compose-port-clash).
• Commits in this monorepo wrapper may go directly on master (user-approved 2026-09-29). In the inner repos (crearte/, crearte-server/, crearte-deploy/): before git commit, run git branch --show-current. If on master, do NOT commit — ask the user for a branch name, create it, and commit there.
• .env is gitignored and must stay that way. Never commit secrets. Any new secret must land in .env.example as an empty placeholder (with a comment) in the same commit that introduces it.
• Changes → docs/CHANGELOG.md of the repo being changed (this wrapper's docs/CHANGELOG.md, or an inner repo's docs/CHANGELOG.md for its own changes). This workspace is not under web/, so CHANGELOG_webui.md never applies. Higher versions on top.
• CHANGELOG entry format: same entry has English line then Chinese line on consecutive lines (no blank line between them); different entries are separated by a blank line.
• Merging into master: always create a merge commit — git merge --no-ff <branch> (never fast-forward, the integration point must be recorded). Delete the merged branch afterwards.
• Compose changes that alter usage must update README.md in the same commit.

Compose invariants (breaking these loses data or breaks the stack)

• Sibling layout: build contexts are ../crearte and ../crearte-server. Never repoint them or inline copies of the app code.
• dev and prod both publish host port 8080 — the profiles are mutually exclusive. Keep it that way unless README is updated accordingly.
• Volume names are data identity: renaming a volume orphans its data. Never rename pgdata-*, bundle-keys-*, minio-data-*, or the *_node_modules volumes.
• db-test (pgdata-test, 127.0.0.1:5432) is the integration-test database and is truncated freely. Never point TEST_DATABASE_URL at dev data — db-debug shares the pgdata-dev volume with db-dev, so a misdirected test run wipes development data.
• Never run docker compose ... down -v unless the user explicitly asks: it destroys postgres data, bundle keys, and MinIO objects, and the MinIO bucket init must then be redone by hand.
• Required secrets use ${VAR:?…} so compose fails fast when missing. Keep the :? guard and .env.example in sync for every new secret.
• The one-time MinIO bucket init (mc mb local/crearte + anonymous download) exists because the volume is empty on first creation — do not silently automate it away; document any change in README.
• Keep depends_on health gating (api waits for service_healthy db); removing it makes first-boot races routine.

Verification (required before claiming a compose change works)

1. docker compose config -q for each touched profile (--profile dev|prod|debug|mock).
2. docker compose --profile <p> up -d --build, then docker compose ps — healthchecks must pass.
3. Smoke-test the affected path (e.g. docker compose exec api-dev wget -qO- http://127.0.0.1:8080/healthz, or the upload flow through http://localhost:8080).
4. Tear down with plain down (never -v) unless the task is specifically about destroying data.

Documentation

• All specs, implementation plans, roadmaps, and cross-repo coordination docs live in this wrapper's docs/ (docs/ROADMAP.md, docs/specs/, docs/plans/). Do not scatter them into the inner repos; their docs/superpowers/ copies are legacy (in crearte that path is gitignored). This supersedes the crearte-deploy 0.3.0 "canonical home" convention.
• Register every new spec/plan in the doc index table at the bottom of docs/ROADMAP.md.

Layout notes

• No app code, no tests, no build scripts live here; those belong to crearte / crearte-server.