Developer Portal

Table of Contents

• 1. Architecture and Contracts
• 2. Documentation Contracts
• 3. Numerical Methods and Models
• 4. Documentation and Maintenance
• 5. Suggested Contributor Read Path
  • 5.1 Agent-Assisted Development
  • 5.2 Clone and Environment Portability
  • 5.3 Spatial Data Model Read Path
• 6. Expected Outcomes

Type HubFor Contributors and maintainersStatus Routing only - see linked pages for detail

This section is for maintainers and contributors changing solver behavior, YAML contracts, or workflow logic. It emphasizes architecture boundaries, method-level reasoning, and safe extension points.

1. Architecture and Contracts

• Code Architecture: module boundaries and runtime ownership model.
• Configuration Contract (YAML -> Generated Artifacts -> Runtime): YAML -> generated artifact -> runtime contract.
• Developer Ingestion Map: where specific YAML keys enter C/Python paths.
• Configuration Extension Playbook: adding new keys/features safely.
• Modular Selector Extension Guide: selector-by-selector hook points for extending current user-facing options.
• C Runtime Execution Map: startup/timestep execution trace across C modules.
• Field Identity and Layout Catalog: typed Eulerian/particle field identities, runtime views, and coupling metadata.
• Field Statistics: scientific field statistics — accumulation, monitoring, checkpoint state, derived output, and extension points.
• LES Turbulence Closure: subgrid closure formulation, the Germano-Lilly procedure, coefficient averaging and limiting, and the kernels a new closure reuses.
• Future Architecture Specifications: the one place planned work is described, with what must exist before each item is accepted.

2. Documentation Contracts

• Documentation Extension Framework: capability, family, and subsystem contracts, lifecycle gates, and concern modules.
• Page Type Contract: which page type you are writing, and what it must refuse to do.
• Capability Status Vocabulary: status words, the known-defect disclosure rule, and evidence facets.
• Scientific Writing Handoff: what the foundational method pages owe, and the scaffolding already in place.

3. Numerical Methods and Models

• Methods and Models Overview: entry map across all numerical method pages.
• CurvIB Method Overview through IEM Mixing and Statistical Averaging: flow solve, pressure solve, coupling, and mixing/statistics internals.
• Momentum Solver Implementations: runtime-dispatched momentum solver implementations.
• Analytical Solution Modes and Initial Condition Modes: initialization and analytical-mode behavior.
• Boundary Conditions Guide: BC handler mapping from YAML to C handler objects.
• Particle Initialization and Restart Guide: seeding and restart/migration behavior.
• Particle Model and Coupling Overview: particle lifecycle and projection coupling.

4. Documentation and Maintenance

• API Documentation Status: current API documentation coverage and gaps.
• Grid, Cell, and Variable Architecture Guide: data-structure contracts in grid/cell storage.
• Maintenance Backlog and Low-Priority Fixes: low-priority but known technical-debt items.
• Documentation Map: alternate categorized entry path.

5. Suggested Contributor Read Path

Begin with the repository-root CONTRIBUTING.md for issue metadata, pull-request scope, reuse expectations, and verification reporting. Then choose only the route needed by the change:

1. Code Architecture and the nearest directory guide.md for ownership.
2. Configuration Contract (YAML -> Generated Artifacts -> Runtime), Developer Ingestion Map, and Configuration Extension Playbook for configuration ingress.
3. Documentation Extension Framework and Modular Selector Extension Guide for capability or subsystem work.
4. C Runtime Execution Map for runtime changes, and the ordered route in 5.3 Spatial Data Model Read Path for field storage, boundary, or ghost work.
5. Testing and Validation Guide plus tests/guide.md for the narrowest evidence that answers the change's risk.

5.1 Agent-Assisted Development

Agent use is optional. AGENTS.md is the canonical shared working agreement; CLAUDE.md imports it. The canonical reusable skills live under .agents/skills/ and byte-identical materialized copies under .claude/skills/ make the setup work in clones whose toolchains do not follow the same discovery convention. Run make audit-agent-setup to verify portability and make sync-agent-skills after an intentional canonical skill edit.

The cross-cutting picurv-technical-communication skill composes with the applicable workflow skill for substantive explanations, plans, findings, recommendations, and technical handoffs. It standardizes audience calibration and evidence-status language; it does not replace the workflow skill or make explanatory documentation authoritative.

Agents use documentation and registries as a bounded index, then inspect the routed code and tests because runtime behavior remains authoritative. The review-packet modes documented in Documentation Extension Framework join those declarations; an optional current Doxygen source-reference cache can further bound caller inspection. Neither mechanism proves behavior. Human and agent contributions owe the same focused scope, reuse search, tests, and explicit list of what was not verified.

5.2 Clone and Environment Portability

The tracked agent audit rejects symlink-only instruction/skill layouts and verifies that .claude/settings.local.json stays untracked through the repository's own exact ignore rule rather than a developer's global Git configuration. Machine-specific permissions remain local. Contributor setup, tests, and documentation commands do not require either Codex or Claude Code.

5.3 Spatial Data Model Read Path

Field storage, boundary treatment, and ghost exchange are owned by separate pages rather than one narrative. Read them in dependency order:

1. Grid, Cell, and Variable Architecture Guide: nodes versus cells, face-centered flux storage, and the shifted-index convention cell-centered variables use.
2. Field Identity and Layout Catalog, sections 3 through 5: the per-field descriptor, the layout-to-boundary conventions, and what UpdateLocalGhosts does after the global-to-local scatter. Section 4 separates decomposition halo entries from solver-layout boundary and dummy indices; read it before writing any kernel that indexes neighbors.
3. Periodic Boundaries and Driven Flows for the periodic grid contract and field synchronization, then Boundary Conditions Guide for handler dispatch.

The catalog's field.identity_and_layout contract is report-only, so confirm layout facts against the code and the live DM before relying on them. make review-packet CONTRACT=field.identity_and_layout reaches the declared symbols and sources without reading these pages end to end.

6. Expected Outcomes

After working through this section, you should be able to:

• trace a new YAML key from schema to runtime consumer,
• identify the right C module for a numerical feature change,
• update docs/tests/validation alongside code changes,
• preserve diagnostics and contract clarity while extending behavior.