Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ jobs:
- run: make ci-check-hardcoded-strings
- run: make ci-check-ci-parity
- run: make ci-check-locales
# Backticked repo paths in docs/, CLAUDE.md, README.md and skills must exist (#519).
# Backticked repo paths in docs/, AGENTS.md, CLAUDE.md, README.md and skills must exist (#519).
- run: make ci-doc-paths
# Fixed sleeps in tests are timing bets; poll with simple_module_test.wait_for.
- run: make ci-check-test-sleeps
Expand Down
513 changes: 513 additions & 0 deletions AGENTS.md

Large diffs are not rendered by default.

4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ All notable changes to this project are documented in this file. The format is b

## [Unreleased]

### Changed

- Docs: the repository's agent guide is now `AGENTS.md`, read by Codex, Cursor and other agents; `CLAUDE.md` imports it and keeps only the Claude Code rules. Both, and the README, were corrected against the code (lint and CI checks, the `/setup` first run, `make migration LABEL=…`, DB-backed settings and the generated `SM_SECRET_KEY`, which modules need `users` under Keycloak, signup as a setting). The README gains a demo GIF, recorded with `scripts/record_readme_demo.py`, and a table of the bundled modules. `make ci-doc-paths` also checks `AGENTS.md`.

### Fixed

- `smpy new` apps keep `simple_module_cli` in the workspace root's `dev` group, so a plain `uv sync` no longer uninstalls it and `uv run smpy` no longer falls through to an older global `smpy`. Inside a project, `smpy` now warns when the project pins the framework to another version than its own (except `new`, `update` and `package-update`), and `smpy doctor` run by a CLI outside the project's venv says so instead of "run it inside a project". Existing apps: add `"simple_module_cli==<version>"` to `[dependency-groups] dev` in the root `pyproject.toml` (#929).
Expand Down
582 changes: 18 additions & 564 deletions CLAUDE.md

Large diffs are not rendered by default.

288 changes: 158 additions & 130 deletions README.md

Large diffs are not rendered by default.

Binary file added docs/assets/readme-demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 6 additions & 3 deletions docs/framework-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,19 +184,22 @@ Two attributes are intentionally kept outside `Services`:
### Module settings

Module settings should:
- Use a per-module prefix: `SM_<MODULE>_*` (e.g. `SM_USERS_ALLOW_SIGNUP`).
- Be stored inside a module-owned dataclass at `app.state.<module_lower>` during `register_settings(app)`.
- Be a `DbBackedSettings` subclass: values come from the constructor and the DB settings store, never from the environment (`SM_<MODULE>_*` is read only by `smpy settings import-from-env`, once).
- Be registered in `register_settings(app)` through `register_module_settings`, which mounts the module's services object at `app.state.<module_lower>`.
- `SM012` diagnostic fires if `register_settings` is overridden but no `app.state.<module_lower>` entry is added.

```python
class UsersModule(ModuleBase):
def register_settings(self, app: FastAPI) -> None:
from simple_module_core.module_settings import register_module_settings
from users.core.settings import UsersSettings
from users.core.state import UsersState

app.state.users = UsersState(settings=UsersSettings())
register_module_settings(app, "users", UsersSettings, lambda s: UsersState(settings=s))
```

Details: [settings](framework/settings.md).

## Database

### Models
Expand Down
2 changes: 1 addition & 1 deletion docs/framework/invalidation.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ A transport failure never propagates. The caller has already committed; turning

Every framework channel shares that one Redis channel; `Invalidation.channel` routes inside the receiving process.

> **A stored override beats the environment.** `simple_module_core.settings_hydrate.hydrate_settings` passes DB values to the settings class as *init args*, and pydantic-settings ranks init args above its env source — so once `background_tasks.broadcast_invalidations` has a row in the settings store (written from the admin UI, or by `smpy settings import-from-env`), the env var above stops having any effect after boot hydration. This inverts the precedence CLAUDE.md states (`env → DB → default`) and is not specific to these two fields: it applies to every env-readable module setting, `broker_url` included. Check the settings screen, not just the container's environment, when a knob appears not to work.
> **A stored override beats the environment.** `simple_module_core.settings_hydrate.hydrate_settings` passes DB values to the settings class as *init args*, and pydantic-settings ranks init args above its env source — so once `background_tasks.broadcast_invalidations` has a row in the settings store (written from the admin UI, or by `smpy settings import-from-env`), the env var above stops having any effect after boot hydration. This inverts the precedence AGENTS.md states (`env → DB → default`) and is not specific to these two fields: it applies to every env-readable module setting, `broker_url` included. Check the settings screen, not just the container's environment, when a knob appears not to work.

> **Redis pub/sub ignores the database index.** A publisher on `redis://host/0` and a subscriber on `redis://host//1` with the same channel name *do* reach each other — pub/sub is server-global, not per-database. So the `dev-services` convention of giving each repo its own logical DB (this one owns 4 and 5) isolates keys but **not** invalidations: two installs left on the default channel name will clear each other's caches, and each will see the other's user ids on the wire. Verified by experiment. Rename the channel per app; do not rely on the DB number.

Expand Down
14 changes: 14 additions & 0 deletions docs/superpowers/plans/2026-11-15-refresh-agent-docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Refresh agent docs: plan

Design: `docs/superpowers/specs/2026-11-15-refresh-agent-docs-design.md`.

| # | Task | Files | Done check | Parallel |
|---|---|---|---|---|
| T1 | Demo GIF recorder + recording | `scripts/record_readme_demo.py`, `docs/assets/readme-demo.gif` | script runs end to end against a live SQLite stack; GIF ≤ 5 MB; frames reviewed | independent (subagent) |
| T2 | AGENTS.md from CLAUDE.md, with the fact-check fixes and trims; CLAUDE.md becomes `@AGENTS.md` + Claude specifics | `AGENTS.md`, `CLAUDE.md` | every rule from the old file is in one of the two; `make ci-doc-paths` | independent of T1 |
| T3 | Doc-path checker scans AGENTS.md; comments citing CLAUDE.md sections | `scripts/check_doc_paths.py`, cited tests/comments, `docs/framework/invalidation.md` | `make ci-doc-paths`; a broken path in AGENTS.md fails it | after T2 |
| T4 | README restructure (embeds the GIF) | `README.md` | every fact-check item addressed; `make ci-doc-paths` | after T1 for the GIF path |
| T5 | CHANGELOG `[Unreleased]` docs entry; `make lint` | `CHANGELOG.md` | `make lint` green | last |

TDD note: this is a docs change. The executable checks are the doc-path checker (T3 adds AGENTS.md
to it and is proven by a deliberately broken path) and the recorder script's own run (T1).
128 changes: 128 additions & 0 deletions docs/superpowers/specs/2026-11-15-refresh-agent-docs-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Refresh AGENTS.md, CLAUDE.md and README (with a demo GIF)

## Goal and scope

Bring the three entry-point docs back in line with the code at `main@ab178587`, add a tool-neutral
`AGENTS.md`, and put a short demo GIF at the top of the README.

In scope: `AGENTS.md` (new), `CLAUDE.md`, `README.md`, a reproducible GIF recorder script, the
committed GIF, the doc-path checker, and the handful of comments that cite CLAUDE.md sections.

Out of scope: the VitePress docs (`docs/**`) beyond what a moved reference needs, `skills/**`
(none of them cites CLAUDE.md or AGENTS.md), and generating agent files for `smpy new` apps.

## Approach

**`AGENTS.md` is the canonical agent guide; `CLAUDE.md` imports it.** Codex, Cursor, OpenCode and
other agents read `AGENTS.md`; Claude Code reads `CLAUDE.md` and follows its `@AGENTS.md` import.
`CLAUDE.md` keeps only what is Claude Code specific: the `Agent` tool model routing and the Codex
subagent rules from "Working in parallel".

Rejected:
- Symlink `CLAUDE.md -> AGENTS.md`: symlinks break on Windows checkouts and leave no place for
Claude-only rules.
- Two full copies: they drift, which is the problem this change fixes.

## Design

### AGENTS.md (moved from CLAUDE.md, fixed and trimmed)

Fixes, all verified against the code:
- `make lint` row and CI paragraph: add the locale, doc-path, test-sleep and raw-fetch checks, the
`docs-build` job, and `alembic check` inside `ci-doctor`.
- Doctor vs dev boot: a dev boot adds `SM012`/`SM031`; `SM025` runs at boot in every environment.
- `make new-module` also runs `smpy openapi gen-types`, so `pages/api.generated.ts` is in the
commit list.
- "Full list" of make targets points at the root `Makefile`; `docs/reference/make-commands.md`
covers the scaffolded app's Makefile.
- Middleware order: add Sentry context (when enabled) and the fixed-tenant Tenant middleware when
`default_tenant` is set.
- Module layout: `models/`, `task_config.py`, `cli.py` are allowed roots; extra root dirs only via
`DOMAIN_AREAS` in `host/tests/test_module_layout.py`.
- Package count `~23` PyPI packages.

Trims (history and API detail that already lives in the linked docs), keeping every "do/don't"
rule:
- Migrations: drop the root/head SHA list and mislabel history; keep "where, `upgrade heads`,
`--head <label>@head`, update `test_migration_graph.py` on a new root or head".
- Configuration: keep env → DB → default, no new env vars, `merge_host_settings()`,
`register_module_settings`; the failure-mode detail stays in `docs/framework/settings.md`.
- Hook bullets, CORS/RateLimit prose, Inertia shared-prop detail, scaffolder internals: one line
each plus the doc link.

Target: about 400 lines (from 590).

### CLAUDE.md

```
@AGENTS.md

## Claude Code specifics
- Working in parallel: subagent model routing (haiku/sonnet/opus), Codex as a subagent.
```

### README.md

Restructured for someone landing on the repo:
1. One-paragraph pitch, the demo GIF, badges are not added (none exist today).
2. **Build an app**: `uvx --from simple_module_cli@latest smpy new my-app`; first page is the
`/setup` wizard until an admin exists; presets (`minimal|standard|full`, `--with`); `smpy add`.
3. **Bundled modules**: a table of the 17 modules, one line each.
4. **Work on the framework**: quickstart that states `make dev` needs the sibling
`../dev-services` stack, and the SQLite-only path (`make dev-api` + `make dev-ui`).
5. Docker (kept, `SM_APP_PORT` sentence fixed).
6. Create a module: `make migration LABEL=orders msg=…` and `branch_labels` on the first revision.
7. Commands table: corrected `make lint`, adds `gen-pages`, `gen-i18n`, `gen-api-types`,
`test-py`/`test-js`/`test-e2e`, `test-py-pg`, `worker`/`beat`.
8. Configuration: `SM_SECRET_KEY` unset → generated and stored in the DB; env-only bootstrap list
corrected (`SM_DATABASE_URL`, `SM_ENVIRONMENT`, `SM_SECRET_KEY`, `SM_VITE_DEV_URL`, `SM_DEBUG`,
`SM_MODULES_ENABLED`, `SM_REDIS_URL`); pool/log/proxy knobs are DB settings that env overrides;
link `docs/reference/env-vars.md`.
9. Auth providers: the Keycloak caveat names only `permissions` (and `api_tokens`, optional) as
needing `users`; signup is the "Allow signup" setting, no restart.
10. Architecture: middleware order replaced by a link to `docs/framework/middleware.md` plus the
short chain; diagnostics list extended.
11. Contributing / for AI agents: `AGENTS.md`, `skills/` and `smpy skills add`; `make lint` runs
every CI check locally.

### Demo GIF

- `scripts/record_readme_demo.py`: Playwright (already a dev dependency) against a running
server, 1280×800 viewport, `record_video_dir`. Flow, ~20 s: sign in → dashboard → admin users
list → a module CRUD page (feature flags: create one) → branding: change the primary colour and
watch the UI re-theme → doctor panel. Then `ffmpeg` palettegen/paletteuse to a 960-px-wide,
12 fps GIF.
- Output committed at `docs/assets/readme-demo.gif`, budget ≤ 5 MB. README embeds it by relative
path, so it renders on GitHub.
- The script takes `--base-url`, `--email`, `--password`, `--out`; the recipe (spare ports, SQLite
file DB, `smpy users create-admin`) is in its docstring.

### Tooling

- `scripts/check_doc_paths.py` also scans `AGENTS.md`.
- Comments that cite CLAUDE.md sections (middleware-order test, lifespan test, dashboard
`doctor.py` "§ Diagnostic codes", `docs/framework/invalidation.md`) point at `AGENTS.md`.

## Decisions made

- AGENTS.md canonical + `@AGENTS.md` import in CLAUDE.md (above).
- Moderate trim (~590 → ~400 lines), not a rewrite: every rule stays, history goes.
- GIF content and location as above; no README screenshots beyond the GIF.
- The recorder script is committed (reproducible GIF), but not run in CI.
- No AGENTS.md for scaffolded apps in this change.

## Testing

- `make lint` (doc-path check now covers AGENTS.md; ruff formats Python fences in the docs).
- Unit test for `check_doc_paths.sources()` including `AGENTS.md`, if the checker has a test file;
otherwise the lint run is the check.
- The recorder script runs once end to end against a live SQLite stack to produce the GIF; I look
at the frames before committing.
- No browser QA of app pages: nothing in the app changes.

## Risks

- Claude Code's `@AGENTS.md` import must resolve from the repo root. I can't open a fresh session
from here to watch it load, so it relies on the documented import syntax; `claude` sessions in
the worktree after the change are the check.
- GIF size: if over budget, drop to 10 fps / 800 px or shorten the flow.
2 changes: 1 addition & 1 deletion framework/hosting/tests/test_lifespan_order.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""Verify ``create_app``'s lifespan walks modules forward and backward.

CLAUDE.md says ``on_startup`` runs in topological order and ``on_shutdown``
AGENTS.md says ``on_startup`` runs in topological order and ``on_shutdown``
in reverse — a regression here means a dependent module's startup hook runs
before its dependency's hook is ready (or, on shutdown, the dependency tears
down resources while the dependent is still using them).
Expand Down
5 changes: 3 additions & 2 deletions framework/hosting/tests/test_middleware_order.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
"""Pin the documented middleware execution order.

CLAUDE.md spells out the pipeline:
AGENTS.md spells out the pipeline:

(ForwardedHost → ProxyHeaders, opt-in; pinned in test_forwarded_host.py)
(SentryContext, only when Sentry is enabled)
CorrelationId → RequestLogging → CORS → BodyLimit → GZip → Security → Session
→ InertiaMiddleware → <module> → Tenant (opt-in) → Locale
→ InertiaLayoutData → RateLimit → Setup → Maintenance
Expand Down Expand Up @@ -127,7 +128,7 @@ def test_middleware_pipeline_order(multi_tenant: bool, expected: tuple[str, ...]
)
app = create_app(settings)
assert _names(app) == expected, (
"Middleware pipeline order drifted from CLAUDE.md. "
"Middleware pipeline order drifted from AGENTS.md. "
f"Got {_names(app)!r}, expected {expected!r}."
)

Expand Down
2 changes: 1 addition & 1 deletion framework/hosting/tests/test_session_cookie_security.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""SameSite/HttpOnly invariants for the framework's session cookie.

CLAUDE.md treats SameSite=Lax as the CSRF defence — there is no explicit
AGENTS.md treats SameSite=Lax as the CSRF defence — there is no explicit
token middleware. If a future Starlette upgrade silently switched the
default to ``None`` (used to be the case on older versions), CSRF
protection would evaporate without any test catching it.
Expand Down
2 changes: 1 addition & 1 deletion framework/hosting/tests/test_strict_discovery_wiring.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
The existing tests cover ``discover_modules`` directly with strict=True, but
nothing pins the wiring — a regression that hard-coded ``strict=False`` would
silently restore the old "drop a broken module and keep booting" behaviour in
production, which is exactly what CLAUDE.md says must not happen.
production, which is exactly what AGENTS.md says must not happen.

Reuses the ``_FakeEntryPoint`` and ``_patch_entry_points`` helpers from
``framework/core/tests/test_discovery.py`` (the canonical location for the
Expand Down
2 changes: 1 addition & 1 deletion modules/dashboard/dashboard/web/doctor.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ class DoctorCheck:


#: The catalogue. Labels live in the locale catalogue keyed by ``id`` — this is
#: the framework's own diagnostic surface (see CLAUDE.md § Diagnostic codes),
#: the framework's own diagnostic surface (see AGENTS.md § Diagnostics),
#: grouped into the questions an operator actually asks.
CHECKS: tuple[DoctorCheck, ...] = (
DoctorCheck("pages", frozenset({"SM003", "SM004"}), "make gen-pages"),
Expand Down
2 changes: 1 addition & 1 deletion modules/users/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Pre-wired into any app scaffolded with `smpy new`.

- Email + password registration, login, logout, password reset.
- Admin invite flow — admin enters an email, recipient clicks a link, sets a password, is logged in.
- Public signup toggle (`SM_USERS_ALLOW_SIGNUP`, default `false`).
- Public signup toggle (the `allow_signup` setting at `/admin/settings/`, default off).
- Bootstrap admin via env vars (`SM_USERS_BOOTSTRAP_EMAIL` + `SM_USERS_BOOTSTRAP_PASSWORD`) — idempotent, only creates if the users table is empty.
- `smpy users create-admin` CLI for ad-hoc admin creation.
- Inertia pages for login/register/invite-accept/admin-invite.
Expand Down
4 changes: 2 additions & 2 deletions scripts/check_doc_paths.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"""Fail when a backticked repo-relative path in the user docs does not exist (#519).

Scans ``docs/**/*.md`` (minus the historical ``docs/superpowers``, ``docs/plans``,
``docs/archive`` and ``docs/release-notes``), ``CLAUDE.md``, ``README.md`` and
``docs/archive`` and ``docs/release-notes``), ``AGENTS.md``, ``CLAUDE.md``, ``README.md`` and
``skills/**/SKILL.md``. A backticked token counts as a path when it has a ``/`` and
either ends with ``/`` or has a file extension, and contains no space or
glob/brace/placeholder characters. A token resolves if it exists relative to the repo
Expand Down Expand Up @@ -46,7 +46,7 @@


def sources() -> list[Path]:
files = [ROOT / "CLAUDE.md", ROOT / "README.md"]
files = [ROOT / "AGENTS.md", ROOT / "CLAUDE.md", ROOT / "README.md"]
for p in sorted((ROOT / "docs").rglob("*.md")):
rel = p.relative_to(ROOT / "docs").parts
if rel[0] in EXCLUDED_DOC_DIRS:
Expand Down
Loading
Loading