# AGENTS.md

Operating instructions for any AI coding agent working in this repository (Claude Code,
Codex, Cursor, Copilot Workspace, etc.). Also see `CLAUDE.md`, which mirrors this for
Claude Code specifically.

## Project summary

Classic ASP application built on **RouteKit**, a custom MVC framework in `core/`. It ships
its own code generators for migrations, models/repositories, and controllers under `scripts/`.
Treat this as a framework with conventions, not a bag of loose `.asp` files — use its tooling.

```
public/              # IIS root — front controller, web.config, static assets
core/                # Framework internals (router, dispatcher, libs) — do not modify casually
app/
  controllers/       # Controllers + autoload_controllers.asp
  models/            # POBOs
  repositories/      # Repository classes (generated alongside models)
  views/             # Views, grouped by controller, plus views/shared/
db/
  migrations/        # Timestamped migration files
  webdata.accdb       # Access database
scripts/             # Code generators + migration runner (VBScript, run via cscript)
tests/               # Dev-only aspunit test harness (separate IIS app from public/)
```

## Rule 1: Use the framework's own scripts for scaffolding

All migrations, models/repositories, and controllers are generated with `cscript` from the
project root. Do not hand-write scaffolding that a generator already produces.

**Migrations**
```bat
cscript //nologo scripts\generateMigration.vbs create_my_table
cscript //nologo scripts\runMigrations.vbs status
cscript //nologo scripts\runMigrations.vbs up
cscript //nologo scripts\runMigrations.vbs down
cscript //nologo scripts\runMigrations.vbs apply <filename>
cscript //nologo scripts\runMigrations.vbs rollback <filename>
```
Output goes to `db/migrations/`. Never edit `db/webdata.accdb` directly or bypass migrations
to change schema.

**Models + repositories**
```bat
cscript //nologo scripts\GenerateRepo.vbs /table:my_table /pk:id
```
Move outputs to `app/models/` and `app/repositories/`.

**Controllers**
```bat
cscript //nologo scripts\generateController.vbs MyController "Index;Show(id);Create;Store"
```
Move the output to `app/controllers/`, then:
1. Include it from `app/controllers/autoload_controllers.asp`
2. Register it in `core/lib.ControllerRegistry.asp`
3. Add routes in `public/Default.asp`
4. Add views under `app/views/MyController/`

If a generator can't do what's needed, say so explicitly before writing anything by hand.

## Rule 2: Ask before assuming

If a request is ambiguous — table/column names, types, primary keys, controller actions,
route paths, business rules — ask a clarifying question rather than guessing. Regenerating
scaffolding after a wrong guess is more expensive than asking up front.

## Rule 3: Propose, then get approval, before changing or adding functionality

Before making a change, state what you plan to do (which scripts you'll run, which files
you'll touch, which registry/route entries you'll add) and wait for approval. This applies
in particular to:
- Migrations (hard to reverse against a shared Access database)
- New or changed controllers, routes, or registry entries
- Any edit inside `core/`
- Edits to `public/Default.asp` or `public/web.config`

Small, clearly-scoped fixes the user directly pointed at don't need a formal proposal — use
judgment, but default to checking in when unsure.

## High-risk files

- `public/Default.asp` — route table
- `public/web.config` — IIS config, connection strings
- `core/mvc.asp` — dispatcher
- `core/lib.ControllerRegistry.asp` — controller whitelist
- `app/views/shared/` — layout shared by every page

## Testing

- Production app: `public/`. Separate dev-only test app: `tests/` (vendored `aspunit`
  framework — see `TESTING.md`).
- No automated CLI test runner exists; validation is manual through IIS, plus `cscript` for
  generator/migration scripts. Say so plainly rather than implying automated coverage that
  isn't there.
- After changing `tests/web.config`, run `cscript //nologo tests\sync-webconfigs.vbs`.

## Reference docs

- `README.md`, `docs/development-instructions.md`, `docs/development-guide.md`