docs(development): update to latest dev process

docs/DEVELOPMENT.md

@@ -1,65 +1,104 @@
-# Development Workflow
+# Development Guide
+
+## Project Structure
+
+```
+pg_morbac/
+├── src/                    # Modular SQL source files
+├── tests/                  # Test files
+├── tools/                  # Build and test scripts
+├── docs/                   # Documentation
+├── pg_morbac.control       # Version source of truth
+├── pg_morbac.sql          # Generated (git-ignored)
+└── Makefile               # Build automation
+```
 
 ## Version Management
 
-This extension uses a single-source version approach:
+Version is defined in `pg_morbac.control` under `default_version`.
 
-- **Version source of truth**: `pg_morbac.control` (the `default_version` field)
+Edit source files in `src/` and commit them. Never edit or commit `pg_morbac.sql` (generated by build script).
-- **Development file**: `pg_morbac.sql` (unversioned, for daily work)
-- **Release files**: `pg_morbac--X.Y.Z.sql` (generated, git-ignored)
 
-## Daily Development
+## Development Workflow
 
-1. **Edit**: Work on `pg_morbac.sql` (no version numbers in the file)
+### Edit Source Files
-2. **Test**: Run `make test` to test changes in a temporary database
+
-3. **Commit**: Commit `pg_morbac.sql` to git regularly
+```bash
+vim src/authorization.sql
+```
+
+### Build and Test
+
+```bash
+make test
+```
+
+This builds from `src/`, creates a temporary database, runs all tests, and cleans up.
+
+### Commit Changes
+
+```bash
+git add src/authorization.sql tests/01_authorization.sql
+git commit -m "Add feature X"
+```
+
+The build script concatenates `src/` files in dependency order (header first, footer last).
+
+## Manual Testing
+
+```bash
+make build
+createdb mytest
+psql -d mytest -f pg_morbac.sql
+psql -d mytest
+dropdb mytest
+```
 
 ## Release Process
 
-When ready to release a new version:
+1. Update version in `pg_morbac.control`
+2. Update `CHANGELOG.md`
+3. Run `make build` and `make test`
+4. Commit and tag:
 
-1. **Update version**: Edit `pg_morbac.control` and change `default_version`
-   ```
-   default_version = '1.1.0'
-   ```
-
-2. **Create release**: Run `make release`
-   - Reads version from `.control` file
-   - Copies `pg_morbac.sql` to `pg_morbac--X.Y.Z.sql`
-
-3. **Test**: Run `make test` with the versioned file
-
-4. **Tag in git**:
 ```bash
-   git add pg_morbac.control pg_morbac--X.Y.Z.sql
 git commit -m "Release vX.Y.Z"
 git tag vX.Y.Z
 git push origin main --tags
 ```
 
-## Upgrade Scripts
+## Makefile Targets
 
-For version migrations, create upgrade scripts:
 ```bash
-# Example: upgrade from 1.0.0 to 1.1.0
+make build      # Build from src/ files
-touch pg_morbac--1.0.0--1.1.0.sql
+make test       # Build and run tests
+make install    # Install to PostgreSQL
+make help       # Show all targets
 ```
 
-These contain only the ALTER/ADD statements needed for the upgrade.
+## Code Style
 
-## Make Targets
+SQL keywords in UPPERCASE. Identifiers in lowercase_snake_case. Always qualify with `morbac.` schema.
 
-- `make test`: Test with development file (temporary database)
+Functions use `verb_noun` pattern. Tables use plural nouns.
-- `make test`: Full test with persistent database
-- `make release`: Generate versioned file from development file
-- `make install`: Create release and install in PostgreSQL
-- `make cleanup`: Drop test database
-- `make help`: Show all targets
 
-## Benefits
+## Adding Features
 
-- No version numbers scattered in code
+1. Edit files in `src/`
-- Clean git diffs (only one file changes during development)
+2. Add tests in `tests/`
-- Versioned files only created at release time
+3. Update `docs/DOCUMENTATION.md`
-- Git tags provide version history
+4. Run `make test`
-- Single source of truth for version number
+5. Commit source files
+
+## Debugging
+
+```sql
+SELECT * FROM morbac.auth_cache ORDER BY last_checked DESC LIMIT 10;
+SELECT morbac.invalidate_auth_cache();
+EXPLAIN ANALYZE SELECT morbac.is_allowed(...);
+SELECT morbac.refresh_hierarchy_cache();
+```
+
+## Resources
+
+See [DOCUMENTATION.md](DOCUMENTATION.md), [PERFORMANCE.md](PERFORMANCE.md), and [ADMIN_GUIDE.md](ADMIN_GUIDE.md).