---
name: Deployment operating guide
version: 1.8.0
status: active
owner: Stoirm Arnold
last_updated: 30-Sep-2026
---
















# Deployment operating guide
















## Purpose
















This file defines the operating process for deploying Arco to an individual or organisation.
















A deployment is a configured runtime instance of Arco for a particular person, organisation or environment. It determines which Arco components are present, where deployment-specific configuration lives, how local sources are referenced, how the system is validated, and when a candidate becomes the live runtime.
















This file owns the deployment process. It does not duplicate the operating rules of modules, Governance or Functions.
















For universal maintained-file conventions, follow the System Manual. For module-specific behaviour, follow the relevant module README. For validation mechanics, follow Dry Runs.
















## Deployment principles
















1. **Deploy from evidence, not assumptions.** Inspect the target environment and authoritative sources before creating the runtime.
2. **Keep Core separate from deployment state.** Core defines reusable behaviour; deployed files are the runtime source of truth for that deployment.
3. **Use a staged deployment.** Build and test in a safe dry-run area before promoting to Live.
4. **Use the target provider during testing where practical.** A local simulation is not enough when runtime depends on provider-native storage, links, permissions or file behaviour.
5. **Deploy only what the runtime needs.** Do not promote test evidence, staging artifacts or empty architecture.
6. **Create required module artifacts when a module is enabled.** If a module needs a Register or other required runtime artifact, deployment should create it rather than leave the enabled module incomplete.
7. **Follow the System Manual for structured artifacts.** Register storage and universal Register behaviour are inherited from [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view).
8. **Use exact file links for deployed references.** Local configuration and runtime routing should point to the actual file or Register, not a merely written relative path or filename where a resolvable link is available.
9. **Keep deployment-specific configuration local.** Paths, links, IDs, local sources and selected values belong in the relevant `readme-*-local.md` or designated deployment configuration source.
10. **Do not expose private Core authoring locations.** Record Core lineage/version; add an upstream distribution source only where a secure canonical distribution endpoint exists.
11. **Start deployed changelogs at the deployment baseline.** Do not copy pre-deployment Core history into the runtime copy.
12. **Correct the owning source when testing exposes a generic defect.** Do not patch only the deployment if the defect belongs in Core.
13. **Technical deployment and user onboarding are separate.** The runtime may be deployed before users are onboarded.
14. **Promotion is not completion until Live has been tested.** Run a post-promotion Dry Run against the Live system and file a deployment report.
15. **Load provider-specific runtime guidance only when relevant.** Runtime compatibility overlays are deployment support files, not universal Arco behaviour; install and route one only where the configured runtime requires it.
16. **Preserve established presentation order.** Numeric/display prefixes may make human scan order obvious, but routing must use logical identity and exact links rather than depend on those prefixes.
















## Deployment outputs
















A normal organisational deployment should produce:
















- deployed architecture and routing files;
- Development runtime with operating guide, local configuration, unresolved/resolved Registers and unresolved/resolved DEV records where the deployment supports system development;
- `readme-system-setup.md`;
- enabled module operating files;
- local module configuration where required;
- Governance where required by the deployment;
- enabled Functions;
- human artifacts selected for deployment;
- Registers required by enabled components;
- a Dry Run evidence area;
- a deployment validation report after Live promotion;
- any provider-specific runtime compatibility overlay required by the configured runtime.
















Do not create a category, folder or runtime artifact solely because Core has a corresponding architectural category. A deployment should contain only files that have an agreed runtime purpose.
















## System Setup
















`readme-system-setup.md` is the deployment manifest.
















It should record the deployment-level state required to understand what is installed and whether the runtime has been promoted.
















At minimum, an organisational deployment should record:
















- organisation or deployment identity;
- deployment status;
- Dry Run start date where applicable;
- live deployment date once promoted;
- promotion date once promoted;
- enabled/disabled state for deployed modules and other selectable components;
- primary AI runtime/provider;
- any provider-specific runtime compatibility overlay installed for that runtime, including its current deployed version where applicable.
















Use Boolean `true` / `false` for enabled state.




Record the runtime/provider at the level needed to select compatible operating guidance. Record an exact model/version only where runtime behaviour materially depends on it; do not create unnecessary model-version churn in System Setup.
















System Setup records that a Role system exists, but **Role assignments do not belong in System Setup**. Role holders are deployment Governance state and should be stored through the Roles mechanism.
















A component may be selected for future use before its deployable implementation exists. Where that happens, deployment must make the gap explicit, must not fabricate implementation files, and must not route normal runtime use to the missing component.
















## Deployment Arco guide




Every deployment must have one root-level `readme-arco-guide.md`.




It is the deployment's first-hop router, not a catalogue, deployment manifest or duplicate operating manual. Construct it from the deployment actually present.




A good guide contains:




- a short Purpose;
- concise Routes;
- Routing rules;
- an explicit `Read when` condition or equivalent for each route.




It should route to the smallest relevant maintained sources and stop when enough context is loaded. It should route to the deployed Arco definition when understanding Arco itself is relevant.




Do not duplicate deeper Register paths or subsystem configuration in the Arco guide when those belong to local companion files. Do not route to human artifacts during ordinary runtime. Do not expose Updater as a normal runtime route or imply that the deployment independently pulls Core changes.




## Runtime compatibility overlays




A runtime compatibility overlay is an optional Deployment operating file containing only the provider/runtime-specific guidance needed for Arco to behave correctly on that runtime.




Reusable Core overlays live under `05-deployment/runtimes/` using `arco-<runtime>-runtime.md`. A deployed copy uses the corresponding `readme-<runtime>-runtime.md` name. Deployments may mirror that folder structure where useful. System Setup records only runtime state and the installed overlay/version; the deployment router owns the exact file route. Do not duplicate the runtime file path in both places.




Arco Core remains provider-agnostic. The overlay must not restate or redefine Arco architecture, module behaviour, Governance, Skills construction standards or other canonical operating rules. It exists only to bridge demonstrated runtime-specific differences such as interpretation behaviour, storage/registration requirements or invocation mechanics.




System Setup records the primary runtime/provider and whether a corresponding runtime overlay is installed. The deployment router should load that overlay only when the active runtime matches it and the current task requires Arco operation. Do not route unrelated runtimes through it.




Where a runtime-specific finding exposes a genuinely provider-independent defect, correct the canonical Core owner instead of accumulating compensating text in the runtime overlay. Where the finding is deployment-specific rather than provider-wide, keep it local.




Do not create runtime overlays speculatively. Promote one only after evidence demonstrates a provider-specific need and the proposed overlay passes the required Dry Run.




## Roles during deployment
















Every organisational deployment must establish the required Governance baseline before normal organisational use.
















A deployment must have exactly one System Governor.
















Role definitions belong in Governance. Role assignments belong in the deployment's Roles configuration/Register, not System Setup.
















The System Governor is responsible for resolving deployment-level ambiguity and approving promotion into shared architecture where required by Governance.
















Champions may later build and test local capability where permitted, but Champion onboarding is not a prerequisite for technical deployment.
















## Universal deployment sequence
















### 1. Inspect the target environment
















Before writing anything:
















- identify the primary AI runtime/provider and storage environment;
- determine whether that runtime requires an approved Arco runtime compatibility overlay;
- identify the intended Live location;
- identify a safe Dry Run location;
- identify existing authoritative sources required by enabled components;
- identify provider-native file types and constraints;
- identify whether required permissions/read-write access are available.
















Do not alter authoritative source material merely to make deployment easier.
















Where organisational Context is enabled, the org chart is the normal bootstrap source for organisational structure unless another authoritative source has been deliberately configured.
















### 2. Confirm the deployment scope
















Confirm which Arco components are intended for the deployment.
















This includes:
















- enabled modules;
- whether shared Development is enabled for the deployment;
- Governance;
- enabled Functions;
- selected human artifacts;
- any component deliberately not yet deployed;
- any runtime compatibility overlay required by the configured runtime.
















Do not infer that every Core component must be installed.
















If a selected component is not yet deployable, record the gap rather than inventing an implementation.
















### 3. Create the Dry Run area
















Create a safe deployment candidate area in the target environment.
















The Dry Run should mirror the intended runtime structure closely enough that file behaviour, links, Registers and routing can be tested realistically.
















The candidate area is temporary staging, not a second runtime.








Create an `outputs/` area if one does not already exist. Dry Run evidence belongs under `outputs/dry-runs/`, alongside the Dry Run Register required by the Dry Run standard. Other generated artifacts without an established owner may use the wider `outputs/` area.
















Do not use the Live runtime as the first place the deployment is assembled.
















### 4. Build the deployment shell
















Create the maintained deployment structure required by the selected components.
















Where the deployment supports shared system development, create:




```text
01-architecture/
└── development/
    ├── readme-development.md
    ├── readme-development-local.md
    ├── dev-unresolved-register.csv
    ├── dev-resolved-register.csv
    └── logs/
        ├── unresolved/
        └── resolved/
```




`readme-development.md` is the deployed operating copy of Core [arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view). `readme-development-local.md` owns exact deployment-specific Development Register/log routes and identifiers. Routine Development work reads only the unresolved Register; the resolved Register is consulted only when history, provenance, supersession or DEV-ID allocation requires it.
































Core-derived operating files use the deployed `readme-*` naming convention.




Where the configured runtime requires an approved provider-specific compatibility overlay, deploy the corresponding runtime operating copy and record it in System Setup. Do not create or install an overlay merely because a provider exists.
















Where local deployment-specific configuration is required, create the corresponding `readme-*-local.md`.
















Create required Registers at this stage rather than enabling a module without the artifacts it needs. A required Register must exist even when it initially contains zero records; blank required infrastructure is different from speculative empty records or folders.








For every maintained runtime file created by the deployment, create or verify the archive location required by the System Manual at the same time. Do not wait until the first update.
















Human artifacts may be deployed where selected, but they are not normal runtime routing sources.
















### 5. Establish deployment-local references
















Replace generic or provisional references with deployment-specific values.
















Use exact resolvable file links for:
















- local operating-file references;
- Register references;
- local source documents where appropriate;
- runtime routing where a direct file link is available.
















Do not leave aspirational locations in local configuration.
















If an artifact does not exist yet and is not required for the enabled runtime, use `null` rather than inventing a path.
















### 6. Configure module controls


For every enabled module, instantiate the universal module controls defined by the Module Manual.


`output_approval` remains a deployment-selected Boolean based on the module and Governance requirements.


Core update distribution and deployment reconciliation are system-level responsibilities. Do not create or retain a deployment/module `automatic_system_updates` toggle.


Do not duplicate module enablement in local module files; enabled state belongs in System Setup.


### 7. Establish Governance state
















For organisational deployments:
















- deploy Governance operating files;
- create any required Governance Registers/configuration;
- establish the System Governor;
- create Role assignments in the Roles mechanism;
- configure any local mappings required by Permissions or Approvals.
















Do not duplicate Role holders in System Setup.
















### 8. Run the pre-live Dry Run
















Validate the candidate deployment before promotion.
















At minimum, test:
















- every intended runtime file can be resolved;
- the Arco guide routes to the correct deployed files;
- local configuration resolves to existing files/Registers;
- enabled modules have their required runtime artifacts;
- required Registers open correctly;
- no private Core authoring locations are exposed;
- no phantom paths or nonexistent runtime references remain;
- Human artifacts are excluded from normal runtime routing;
- components without deployable implementations are not incorrectly routed;
- test/staging artifacts are identifiable and separable from runtime content;
- System Setup identifies the intended runtime/provider;
- any configured runtime overlay is present, versioned and loaded only for the matching runtime.
















Where the Dry Run exposes a generic defect in Core, correct Core first, then reconcile the candidate deployment and rerun the affected tests.
















### 9. Review the promotion set
















Before promotion, explicitly distinguish:
















**Promote**
- maintained runtime files;
- local configuration;
- required Registers;
- required runtime folders.
















**Do not promote**
- Dry Run outputs/evidence;
- temporary write-test files;
- staging folders;
- deployment-only scratch files;
- empty architectural folders with no agreed runtime artifact.
















The promotion set should be intentional rather than a blind copy of the entire Dry Run directory.
















### 10. Promote to Live
















Promote the accepted maintained runtime into the Live location.
















At promotion time:
















- change deployment status to `live`;
- record `deployed_at`;
- record `promoted_at`;
- retain the Dry Run start date as deployment history;
- repoint Dry Run links to exact Live file links;
- verify all local READMEs reference Live artifacts rather than Dry Run equivalents.
















Do not consider promotion complete while local files still point back to the candidate environment.
















### 11. Run the Live acceptance Dry Run
















After promotion, run a fresh Dry Run **against the Live runtime itself**.
















This is a deployment acceptance test, not merely a repeat of the pre-live candidate test.
















Verify:
















- all intended Live files resolve;
- Live routing works end to end;
- local configuration points to Live files and Registers;
- required Registers exist and are readable;
- System Setup records the correct live state and dates;
- omitted test/staging artifacts are not part of the Live runtime;
- provider-specific storage and link behaviour work as expected;
- no new contradictions have appeared through promotion;
- runtime/provider state in System Setup matches the Live environment and any runtime overlay resolves only when applicable.
















Save the Live acceptance evidence under the Live deployment's `outputs/dry-runs/` area and record the run in the Dry Run Register.








If a defect is found, correct the owning source, reconcile Live, and rerun the affected checks.
















### 12. File the deployment report
















A successful deployment must end with a deployment validation report.
















The report should record:
















- deployment identity;
- source Dry Run area;
- Live runtime location;
- promotion date;
- promoted structure;
- deliberately omitted material;
- checks performed;
- defects found;
- corrections applied;
- final result.
















Store the report with Dry Run/deployment evidence rather than as normal runtime context.
















A deployment is considered successfully tested only when the final report records no unresolved failed acceptance checks.








After successful Live acceptance, the pre-live candidate workspace is no longer an operating environment. Remove the obsolete candidate runtime and temporary staging material unless a failed test, accepted exception or other retained evidence still requires a specific artifact. The Dry Run Register and any retained exceptional evidence remain the durable validation record.
















## Microsoft 365 / SharePoint deployment
















This section describes provider-specific implementation details for Microsoft 365 deployments. These are not universal Arco architecture rules.
















### Storage
















Use organisation-controlled SharePoint/OneDrive storage according to the intended runtime scope.
















Typical pattern:
















```text
SharePoint document library
├── Dry runs/
│   ├── [candidate runtime]
│   └── outputs/
└── Live/
    └── [promoted runtime]
```
















User-local Arco state may live in the user's own OneDrive where the deployment deliberately uses private user storage.
















### Registers
















Register storage format follows [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view); Deployment does not define a competing format.
















Registers must remain plain and machine-readable:
















- one flat table;
- one header row;
- one record per row;
- no merged cells;
- no decorative title blocks;
- no charts or dashboard layout unless separately required;
- only light functional formatting;
- sortable/filterable columns.
















### File links
















Use resolvable SharePoint/OneDrive file URLs in local configuration and routing instead of written relative file paths where the provider exposes a stable link.
















When promoting from Dry Run to Live, repoint references to the Live item URLs.
















### SharePoint document libraries
















SharePoint sites may contain more than one document library.
















Deployment tooling must target the intended library explicitly and verify the resulting destination.
















A connector or automation may default to `Shared Documents` even when the intended runtime is in another library. Treat this as an implementation concern, not an Arco architectural rule.
















Where direct writes to the intended library are unreliable, a safe provider-specific workaround may stage the item in a writable location and then copy/move it to the exact target library. The deployment must verify the final target and remove temporary staging material.
















### Asynchronous copies
















SharePoint folder copies may be asynchronous.
















Do not assume a successful copy request means the destination is immediately ready. Verify representative files — and ultimately every required runtime file during acceptance testing — before treating promotion as complete.
















### Provider-specific acceptance checks
















In addition to the universal Live checks, confirm:
















- the intended SharePoint document library contains the runtime;
- required Registers resolve from their Live links;
- SharePoint/OneDrive links in local configuration open the intended items;
- no staging copy remains in `Shared Documents` or another temporary location;
- Dry Run evidence has not been copied into the Live runtime.
















## Individual deployments
















A personal deployment may legitimately be much smaller than an organisational deployment.
















It may omit organisational Governance where Roles, Permissions and Approvals have no practical purpose.
















Do not force organisational structure into an individual deployment merely for consistency.
















The staged Dry Run → Live → Live acceptance pattern still applies where the deployment has a meaningful Live runtime.
















## Deployment and onboarding
















Technical deployment and user onboarding are separate processes.
















Deployment establishes the system and its runtime foundations.
















Onboarding introduces the System Governor and later users to that deployed system and populates user-specific Context progressively.
















A future guided deployment experience may combine the two operationally, but the maintained rules should keep their responsibilities distinct.
















## Updates after deployment


A deployed system remains the runtime source of truth for that deployment.


Future Core updates are reconciled deliberately into deployed Core-derived files. Arco Updater is invoked by a Core/update workflow against an explicitly supplied deployment target; the presence of a deployed Updater operating copy does not make the deployment self-update or pull Core independently.


Use the [Core Change Register](https://drive.google.com/file/d/1qCr1CRhkxS1ZBKW3aT6WWcj2AIEym3KC/view?usp=drivesdk) as the bounded index of approved Core version changes when identifying which deployed components may require reconciliation. Where a deployment predates Register coverage or its recorded lineage is incomplete, Updater must fall back to direct Core/deployment comparison.


The old `automatic_system_updates` deployment/module control is retired. Future distributed-update or rollback mechanics remain Development work until explicitly designed, evidenced and promoted.


Generic improvements discovered in a deployment should be corrected in Core before being redistributed where the behaviour is genuinely universal.


Organisation-specific improvements should remain local unless deliberately promoted into Core.


## Boundaries
















Deployment does not:
















- own module-specific behaviour;
- define organisational truth that belongs in Context;
- own Role, Permission or Approval mechanics;
- own Dry Run test mechanics;
- turn test evidence into runtime context;
- require every Core architectural category to exist in every deployment;
- require provider-specific implementation details outside the relevant provider section.


















## Canonical references


[arco-module-manual.md](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view), [arco-governance.md](https://drive.google.com/file/d/1JmdNUNPVJLxFbNQKYS3cJTnDPJ6hRvxb/view), [arco-dry-runs.md](https://drive.google.com/file/d/1Fe2PJd-IGIE5UlZmOlr0d3mThRkKbhX7/view).


## Changelog


| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 30-Sep-2026 | 1.8.0 | Added the Core Change Register to post-deployment reconciliation and retired the obsolete `automatic_system_updates` deployment/module control in line with the current Core-driven Updater model. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 30-Sep-2026 | 1.7.1 | Corrected Development Register names to the current owning contract. | Stoirm Arnold — Defrag invocation | Codex Work |
| 23-Sep-2026 | 1.7.0 | Defined the root-level bounded `readme-arco-guide.md`, replaced the deployed Development Log model with two Registers and unresolved/resolved DEV paths, preserved presentation ordering and clarified Updater directionality. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 22-Sep-2026 | 1.6.0 | Clarified runtime-overlay responsibility: System Setup records runtime state and installed overlay/version; the deployment router alone owns the exact runtime file route, avoiding duplicated path authority. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 22-Sep-2026 | 1.5.0 | Established the canonical Core location and naming for runtime compatibility overlays under `05-deployment/runtimes/`, while keeping deployed placement deployment-specific and owned by System Setup. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 22-Sep-2026 | 1.4.0 | Added provider/runtime state to System Setup and defined conditional runtime compatibility overlays as Deployment-owned, evidence-driven adapters that must not redefine canonical Arco behaviour. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |