---
name: Arco module manual
version: 0.1.1
status: active
owner: Stoirm Arnold
last_updated: 15-Sep-2026
---

# Arco module manual

## Purpose

This file defines the universal contract that every Arco module must follow.

It exists so new modules can be created consistently without each module redefining shared module architecture.

This manual does **not** own universal maintained-file construction or maintenance rules. All maintained module files follow `arco-system-manual.md` for naming, metadata, versioning, changelogs, archives, change control and Dry Run requirements.

This manual also does not redefine Permissions or Approvals mechanics. Those remain owned by Governance.

## Position in the waterfall

Arco's singular-pointer architecture is defined by `arco-readme.md`.

Within that architecture, module construction follows:

```text
arco-readme.md
        ↓
arco-module-manual.md
        ↓
module README
        ↓
deployment/local module configuration
        ↓
module outputs
```

The Module Manual owns only universal module requirements.

A module README owns only behaviour specific to that module.

Deployment/local configuration owns the deployment's selected values.

Do not copy universal module rules into every module README.

## Universal module requirements

Every Arco module must define:

1. **Purpose** — what durable system knowledge or behaviour the module owns.
2. **Boundary** — what belongs inside the module and what explicitly does not.
3. **Outputs** — what the module creates, maintains or makes available through normal use.
4. **Dependencies** — which other Arco layers, modules or external authoritative sources it relies on.
5. **Access scope** — the resource/scope that Governance can use to determine who may access or use the module.
6. **Deployment/local requirements** — any configuration that must be supplied by a deployment.
7. **Lifecycle state** — its current maturity/status in the canonical module catalogue.
8. **Maintenance route** — its maintained files follow the System Manual rather than redefining file-maintenance rules.

A module should contain only the structure needed for its actual use. Do not add registers, roles, approval stages, files or supporting systems merely because they may be useful later.

## Standard module controls

Every enabled module exposes two simple deployment controls.

### Automatic system updates

Default: **ON**.

This controls whether validated changes to the module's deployed/local operating or configuration files may be published automatically.

Governor-facing setup language should be plain:

> Automatic system updates are on. Arco can improve this module's local operating instructions when real use exposes a better way of working. Would you like changes to require your approval instead?

If automatic system updates are turned OFF, proposed maintained-system changes follow the shared proposal → Dry Run → approval → publish route.

This setting never grants a deployment authority to rewrite upstream Arco Core.

### Output approval

This controls whether the module's outputs require approval before becoming final/effective.

Governor-facing setup language should be plain:

> Do the things this module creates or changes need approval before they become final/effective?

If Output approval is OFF, authorised users may create or update eligible outputs without an additional approval step.

If Output approval is ON, the output is routed through the shared Approvals mechanism before becoming final/effective.

Permissions still determine who is authorised to access and use the module.

## Advanced controls

Normal onboarding should remain simple.

A deployment may later expose more granular approval or workflow controls where a real use case requires them, but those controls are not part of the default module setup.

Verification and other specialised lifecycle states belong to the relevant module if they are later proven necessary.

## Relationship to Governance

The Module Manual requires modules to expose the standard controls and an access scope.

Governance owns the mechanics beneath them:

- `arco-permissions.md` owns who may access/use the module;
- `arco-approvals.md` owns how required consent is obtained and returned;
- module-specific READMEs may define which outputs/actions exist, but must not recreate shared Governance mechanics.

## Relationship to the System Manual

All maintained module files follow `arco-system-manual.md`.

The System Manual owns:

- file naming and format;
- YAML metadata;
- versioning;
- changelogs;
- archive behaviour;
- creation/editing rules;
- validation triggers;
- rollback and maintained-file change control.

The Module Manual must not repeat those rules.

## Module creation

A new module should be built by:

1. reading `arco-readme.md`;
2. reading this Module Manual;
3. following `arco-system-manual.md` for maintained-file construction;
4. defining only the module-specific purpose, boundary, outputs, dependencies, access scope and local requirements;
5. adding the module to `arco-modules.md` at the appropriate maturity state;
6. validating any material architecture/change before promotion.

A future Module Builder should automate this sequence rather than maintain a separate copy of the rules.

## Module Builder

A future Module Builder should treat this file as its canonical module-construction contract.

The Builder may guide a user through module creation, generate the required module-specific files/configuration and run the required validation, but it must consume this manual and the System Manual rather than embed duplicate rules of its own.

## Boundaries

This manual does not:

- define what Arco is — `arco-readme.md` owns that;
- define universal maintained-file rules — `arco-system-manual.md` owns those;
- define the module catalogue/maturity — `arco-modules.md` owns that;
- define deployment-specific selected values — System Setup/deployment configuration owns those;
- define Permission mechanics — `arco-permissions.md` owns those;
- define Approval mechanics — `arco-approvals.md` owns those;
- define the detailed behaviour of any individual module.

## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 15-Sep-2026 | 0.1.1 | Renamed the canonical module contract from `arco-module-standard.md` to `arco-module-manual.md` and updated its internal naming/pointer terminology without changing module behaviour. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.1.0 | Created the universal Arco module contract, including module boundaries, required module definition fields, standard deployment controls, the System Manual/Governance boundaries and the future Module Builder inheritance model. | Stoirm Arnold | GPT-5.6 Sol |