Standard App Structure — v2 (validated against real folder tree, piloted on `defapp`)

`defapp` was the old standard. This version corrects it against what's actually
in production across `register`, `aiwizard`, and `aicode`, and is being tested
by updating `defapp` itself before rolling out further.

Mandatory per-app skeleton

```
voice/
├── voice.index.php # entry point, dot-segment naming
├── public/ # web-servable root ONLY — everything else stays outside webroot
├── admin/ # admin views/routes for this app
├── pages/ # app pages/routes
├── templates/ # shared layout templates (NOT "tmpl" — corrected from v1 draft)
├── config/
│ └── templates/ # config file templates
├── css/
│ └── themes/ # theme overrides (integrates with system-tier theme-manager)
├── js/
├── img/
├── php/ # app-specific PHP includes/logic
├── data/
│ ├── config/
│ ├── fonts/
│ ├── logs/ # logs live HERE, not a top-level logs/ — corrected from v1 draft
│ └── sql/
├── docs/
│ ├── adr/ # architecture decision records (from aiwizard)
│ └── runbooks/ # from aiwizard
├── ai/
│ ├── prompts/
│ └── output/
├── audit/ # app-specific audit checks (declared mandatory per app now)
├── tests/ # NOT "test" — corrected from v1 draft
├── scripts/ # one-off/maintenance scripts for THIS app
├── tools/ # maintained reusable CLI for THIS app
├── tmp/ # scratch/ephemeral, gitignored
└── var/
└── sessions/ # runtime state (PHP sessions, from register)
```

Correction from v1: `scripts/` and `tools/` are mandatory per-app (not
system-only as originally proposed) — real apps already keep app-specific
scripts/tools alongside system-wide ones. Both tiers get both folders; the
placement rule (below) decides which specific file goes where.

Optional: `src/{Controllers,Helpers,Parser}/` (or app-specific namespaces
like `aicode`'s `Database/Diagnostics/Logging/Models`) — only for apps that use
OOP/namespaced classes rather than the procedural style. Not every app needs this.

Optional declared extension zones (per app, audited only if declared)

```
voice/
├── api/ # REST API layer (family-tree)
├── python/ # non-PHP runtime — venv itself is gitignored, never committed
├── assets/ # uploads, photos, exports (family-tree)
└── themes/ # only if beyond the standard css/themes/ override
```

System tier — same mandatory-skeleton logic, system-wide scope

```
system/
├── .env # golden rule: single source of truth for system-wide config
├── config/
├── data/
│ └── project.registry.json
├── logs/
├── audit/ # cross-app compliance checks — mandatory at this tier
├── tests/ # tests the shared tooling itself — mandatory at this tier
├── tools/
│ └── theme-manager/ # shared across apps — moved here, not a peer app
├── scripts/
├── docs/
└── php/
└── aicode/ # shared library code — moved here, not a peer app
```

The single placement rule (unchanged, still the test for every file)

> If a folder's contents apply to more than one app, or govern the tooling
> system itself, it belongs under `system/`, declared as a system extension.
> If a folder's contents are specific to one app's own behavior or
> requirements, it belongs under that app, declared as an app extension.

Open item — not yet resolved by the tree alone

Where the app-level `.env` actually lives is unclear from directory names
alone (hidden files don't show in a tree listing). Confirm before the pilot:
does each app have its own `.env` under `config/`, or do all apps read only
from the system-tier `.env`? This decides whether "golden rule" is one file
or one-per-app.

Pilot: what changes in `defapp` to test this

`defapp` currently has: `admin, ai/{output,prompts}, audit, config, css/themes,
data/{config,fonts,logs,sql}, docs, img, js, pages, php, scripts, sql, src/
{Controllers,Helpers,Parser}, templates, tests, tmp, tools`.

To bring it in line with v2, add:
- [ ] `public/` — carve out the actual web-servable files from wherever they
currently sit (likely `pages/` or app root); everything else stays private
- [ ] `var/sessions/` — if defapp handles its own sessions rather than a shared
mechanism
- [ ] `docs/adr/` and `docs/runbooks/` — currently `docs/` is flat
- [ ] `config/templates/` — currently `config/` is flat
- [ ] Resolve the redundant `sql/` vs `data/sql/` — pick one (recommend
`data/sql/` only, drop the top-level `sql/`)
- [ ] Decide whether `src/` (OOP) or `php/` (procedural) is defapp's actual
pattern — right now it has both, which suggests a style that hasn't
fully committed either way

Nothing here needs `api/`, `python/`, or `assets/` — defapp has no declared
extensions, which is correct for a default/reference app.