spfn 0.3.0-beta.6 → 0.3.0-beta.8

package/README.md

@@ -145,9 +145,15 @@ no pre-build needed.
 | `-p, --port <port>` | SPFN server port (sets `SPFN_PORT`) | `spfn.config.js` `ports.server`, then `8790` |
 | `-H, --host <host>` | SPFN server host (sets `SPFN_HOST`) | `spfn.config.js` `host`, then `localhost` |
 | `--allow-pending-migrations` | Start even when migrations are pending (they are listed as a warning) | off |
+| `--no-agent-files` | Do not write the SPFN instruction block into `AGENTS.md` (same as `SPFN_AGENT_FILES=0`) | writes on |
 
 Note: hot reload is **off by default** — pass `--watch` to restart on file changes.
 
+On startup `spfn dev` refreshes a marked block of SPFN conventions in the project's
+`AGENTS.md` (creating the file, and a `CLAUDE.md` that references it, when absent) so
+coding agents read the right idioms. Only the marked region is rewritten, and only when
+its content actually changed.
+
 Pending migrations stop the boot — see [Database](#spfn-db) for what the refusal looks
 like and how to override it.
 
@@ -697,11 +703,25 @@ docker-compose.yml                   # Postgres + Redis (dev)
 docker-compose.production.yml
 Dockerfile, .dockerignore
 next.config.ts                       # patched when auth is enabled: /_auth/:path* rewrite → SPFN API
-.env.example                         # committed reference — every key, placeholder values
+.env.local.example                   # committed reference — Next.js keys, placeholder values
+.env.server.example                  # committed reference — backend keys, placeholder values
 .env.local                           # generated, gitignored (values loaded by Next.js)
 .env.server                          # generated, gitignored (server secrets: DB, cache)
 ```
 
+The reference is split by consumer, never combined, and a key's file follows who
+reads it rather than whether it is secret:
+
+- `.env.local` / `.env.local.example` — the Next.js process (server routes, proxy,
+  SSR) and, through `NEXT_PUBLIC_*`, the browser: `SPFN_API_URL`, `SPFN_APP_URL`,
+  `SPFN_AUTH_SESSION_SECRET`, `SPFN_AUTH_SESSION_TTL`, `SPFN_AUTH_CSRF`.
+- `.env.server` / `.env.server.example` — the SPFN backend only, never loaded by
+  Next.js: `NODE_ENV`, `SPFN_LOG_LEVEL`, `DATABASE_URL`, `CACHE_URL`, `DB_POOL_*`,
+  and every OAuth, token, and admin secret.
+
+So the session secret is secret and still lives in `.env.local` — the Next.js proxy
+verifies cookies with it — while `DATABASE_URL` never appears there at all.
+
 Full mode overlays the Prototype-to-Production baseline:
 
 ```
@@ -720,7 +740,7 @@ next.config.ts                       # /_auth/* callback rewrite
 
 The full RPC proxy imports the auth interceptor and merges `authRouteMap`. Internal auth
 keys are generated with cryptographic randomness in ignored local env files;
-`.env.example` contains placeholders only. Add only the provider keys you use, then run
+`.env.local.example` and `.env.server.example` contain placeholders only. Add only the provider keys you use, then run
 `pnpm spfn db migrate`.
 
 Operating the app is [`spfn ops`](#spfn-ops), not a dashboard: the starter