# CLAUDE.md

Instructions for Claude Code (and any AI coding agent) working in this repository.

## What this project is

This is a Classic ASP application built on **RouteKit**, a custom lightweight MVC framework
that lives in `core/`. It is not a generic Classic ASP codebase — it has its own conventions
for migrations, models/repositories, controllers, and routing, plus code generators for each.
Always work through the framework's own tooling instead of hand-rolling equivalents.

```
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/)
```

## Golden rule: use the framework's generators, don't hand-write scaffolding

When a task calls for a new table, model, repository, or controller, use the generator
scripts under `scripts/` rather than authoring the files by hand. These are run with
`cscript //nologo` from the project root (Windows Script Host, not Node/Python).

### 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>
```
Generated migration files land in `db/migrations/`. Never edit `db/webdata.accdb` directly or
write ad-hoc scripts to alter schema — go through a migration.

### Models + repositories
```bat
cscript //nologo scripts\GenerateRepo.vbs /table:my_table /pk:id
```
Move the generated POBO into `app/models/` and the generated repository into
`app/repositories/`.

### Controllers
```bat
cscript //nologo scripts\generateController.vbs MyController "Index;Show(id);Create;Store"
```
Move the generated file into `app/controllers/`, then wire it up:
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. Create matching views under `app/views/MyController/`

Only fall back to writing a controller, model, repository, or migration by hand if the
generator genuinely cannot produce what's needed (say so explicitly, and explain why).

## Always ask clarifying questions before starting

Before implementing anything non-trivial — a new feature, a schema change, a new
route/controller, a change to `core/` — ask the user clarifying questions if requirements are
ambiguous. Don't guess at table names, field types, primary keys, controller action lists, or
route paths. It's cheaper to ask than to regenerate scaffolding.

## Always propose a plan and get approval before changing or adding functionality

For anything beyond a trivial fix, tell the user what you intend to do — which generators
you'll run, which files you'll move/edit, which routes/registry entries you'll touch — and get
explicit approval before making the change. This includes:
- Any migration (schema changes are hard to reverse against a shared `.accdb`)
- Any new/changed controller, route, or registry entry
- Any edit inside `core/` (framework internals — high blast radius)
- Any edit to `public/Default.asp` or `public/web.config`

Trivial, obviously-scoped fixes (typo, dead code removal the user pointed at directly) don't
need this ceremony — use judgment, but default to asking when in doubt.

## High-risk files — extra care

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

## Testing

- Production app is rooted at `public/`; there is a separate dev-only `tests/` IIS app using
  the vendored `aspunit` framework — see `TESTING.md`.
- There is no automated CLI test runner; validation is manual via IIS-hosted browsing, plus
  `cscript` for generator/migration scripts. State this limitation rather than claiming
  automated test coverage that doesn't exist.
- If you change `tests/web.config`, re-run `cscript //nologo tests\sync-webconfigs.vbs`.

## See also

- `README.md` — quick setup and project structure
- `docs/development-instructions.md`, `docs/development-guide.md` — more workflow detail
- `AGENTS.md` — same operating rules, framework-agnostic phrasing for non-Claude agents
