# Adminive Codex Instructions

## Mandatory skill usage

- Use `$adminive-development` before editing Adminive runtime/API/protocol code, adapters, the Gallery frontend, tests, CMake, install/export, or packaging behavior.
- If the task touches `third_party/Structive/`, also read `third_party/Structive/AGENTS.md` and use its `$structive-development` workflow. Structive rules override this file inside that subtree.
- Do not use Git commands or modify repository history.

## Project purpose

Adminive projects ordinary C++ business objects into backend-admin capabilities. The backend definition is the source of truth for object descriptors, field presentation, form/collection views, page composition, JSON/HTTP contracts, AMIS schemas, managed mutation, status, and transactions. The React frontend consumes generated contracts and must not maintain a second business-field schema.

Read `README.md` for usage and `backend/library/DESIGN.md` for architecture before changing public behavior.

## Architecture boundaries

- `third_party/Structive`: intrinsic property/schema/constraint/synchronization/runtime-structural capability. It must not learn Adminive UI, HTTP, AMIS, CRUD, or persistence semantics.
- `backend/library`: Adminive Core protocol. Keep it independent of concrete JSON libraries, HTTP frameworks, enum libraries, PFR, and frontend frameworks.
- `backend/service/include/adminive/adapters`: concrete bridges for nlohmann JSON, magic_enum, Boost.PFR, cpp-httplib, and Drogon.
- `backend/service/src`: example runtime, Gallery, persistence sample, and server wiring. Do not move reusable protocol behavior here.
- `frontend`: renderer/documentation client. It consumes descriptors/views/manifests/AMIS; do not duplicate C++ business fields in React.

When deciding where a feature belongs, preserve this dependency direction:

```text
Structive -> Adminive Core -> Service adapters -> Example runtime/frontend
```

## Compatibility and implementation rules

- Preserve the existing function signature and semantic contract whenever modifying an existing function.
- If replacing an implementation, delete the old implementation. Do not add compatibility shims unless the design explicitly requires compatibility.
- Do not introduce a second implementation path merely to support old behavior.
- Add validation at the outer protocol/transport boundary when needed; do not repeat equivalent checks in every inner layer.
- Static facts belong in C++20 `constexpr`, concepts, `requires`, or schema validation. Dynamic input belongs in runtime validation.
- `managed writable` is not the same as frontend `editable`/`creatable`.
- `sensitive` fields must not leak through frontend data or default-bearing descriptors.
- Collection query capability is enforced by the backend View Schema. Transport adapters must not silently grant or silently ignore unsupported sort/search/filter fields.
- `frontend` composition delegates final layout to the frontend; other composition kinds retain backend semantic positioning.
- AMIS is an adapter target, not the business description language.
- Synchronization is for in-process mutable consistency. `Resource_Transaction` is for external prepare/commit/rollback. Do not merge those concepts.

## Coding style

- C++ uses K&R brace style.
- Do not add meaningless blank lines.
- Keep comments adjacent to the code they explain; do not separate a comment from its code with a blank line.
- Prefer small semantic functions over compatibility wrappers or defensive checks at every layer.
- CMake paths must be relative to the `.cmake`/`CMakeLists.txt` that owns them, normally through `CMAKE_CURRENT_LIST_DIR`. Do not base project paths on `CMAKE_SOURCE_DIR`/`PROJECT_SOURCE_DIR` unless the existing design explicitly requires it.
- Do not change build/output path patterns or add random path components.
- If a PowerShell script is needed, write it for PowerShell 7 and run it with `pwsh`.

## Tests and verification

- Tests must use `ADMINIVE_CHECK`, not standard `assert()`, because Release defines `NDEBUG`.
- Public headers must remain independently includable; keep header compile tests up to date when adding/removing public headers.
- Protocol changes require focused unit/protocol tests and transport tests when the behavior is visible over HTTP.
- Changes to install/export/package behavior require install-consumer and package ZIP tests.
- Changes to frontend TypeScript/React require `npm run build`; renderer/protocol logic should also run `npm run test:unit`. Browser-visible behavior should run the Playwright E2E gate when dependencies are available.
- Do not claim a verification step passed unless it was actually executed.

Useful commands from the repository root:

```text
cmake -S . -B verification/debug -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON
cmake --build verification/debug
ctest --test-dir verification/debug --output-on-failure
python scripts/verify.py
```

For a focused test, build and run the smallest affected target first, then run the broader gate before handoff.

## Packaging

- `package_zip` is part of the release contract. Keep `AGENTS.md`, `.agents/skills/`, and the nested Structive guidance in the source archive.
- Generated source ZIP timestamps must use China Standard Time (`UTC+08:00`).
- Do not package build directories, `node_modules`, frontend build output, test reports, temporary verification trees, or stale removed implementations.

## Review priorities

When reviewing a change, check in this order:

1. Public signature/semantic compatibility.
2. Layer ownership and dependency direction.
3. Descriptor/View/Composition/HTTP contract consistency.
4. Sensitive/write/query authorization boundaries.
5. Managed synchronization and transaction behavior.
6. Adapter parity, especially httplib versus Drogon.
7. Independent public-header compilation, install consumer, package contents, frontend build, and E2E coverage.
## Dependency and release policy

- Source-tree builds may use the pinned nlohmann/json, magic_enum, and cpp-httplib copies under `backend/service/third_party/include`; installed Adminive adapter targets must resolve those dependencies through their external CMake packages instead of installing bundled headers into the consumer's generic include namespace.
- Keep `THIRD_PARTY_NOTICES.md`, `third_party/licenses/`, `RELEASE.md`, install-consumer checks, and package ZIP checks synchronized with dependency version changes.
- The repository does not declare an outbound license for Adminive/Structive project-owned code. Do not invent or infer one.
- Release verification against Drogon must include the opt-in real dependency gate: `python scripts/verify.py --real-drogon`. Fake Drogon tests remain fast contract tests, not a substitute for that release gate.