--- name: Arco version: 1.29.1 status: active owner: Stoirm Arnold last_updated: 30-Sep-2026 --- # Arco **Arco is what the AI runs on.** Arco is an operating system for working with AI. It provides the maintained context, capabilities, perspectives, rules and configuration that allow humans and AI to work consistently inside an individual or organisation. Arco is not an AI model, assistant or application. It is the operating layer around them. > **Arco is the operating layer through which humans and their AI work inside an organisation.** ## Purpose AI is increasingly involved in everyday work: answering questions, giving advice, performing workflows and making or supporting decisions. Without a shared operating layer, each AI interaction can depend on whatever context happens to be available in that conversation. Important knowledge becomes fragmented across chats, instructions become inconsistent, and different people can receive different answers to the same organisational question. Arco provides a maintained operating system outside individual conversations so that AI does not have to reconstruct how it should work every time it is used. It gives a deployment: 1. **Durable understanding** — maintained context about the person, organisation and environment in which AI is operating. 2. **Repeatable capability** — common structures and standards for defining, maintaining and invoking useful capabilities. 3. **Controlled authority** — clear rules for who or what can act, approve, change or access something. 4. **Reliable routing and configuration** — a way to determine what is available in the deployment and load the smallest relevant operating sources for the task. 5. **Evidence-driven evolution** — a mechanism for improving the operating system through demonstrated use without relying on individual chats as durable state. These are operating functions, not a fixed list of modules. Modules, Governance and Functions implement them as needed by each deployment. `Governance` is a foundational Arco subsystem for organisational deployments. It owns the authority model and routes to Roles, Permissions and Approvals; it is not a normal optional module. Arco does not prescribe all of the work AI performs. It provides the structure through which durable AI capability is defined, found, constrained and evolved. The objective is not to create more systems. It is to give AI a dependable operating layer through which existing organisational knowledge, tools and processes can be used coherently. ## Core and deployments Arco separates the reusable operating system from the organisation that uses it. ```text Arco Core ↓ deployed Organisation readme-X.md ↓ Organisation readme-X-local.md ``` ### Arco Core **Arco Core** contains reusable, organisation-agnostic operating rules. Core files use stable logical `arco-*.md` names. A Core directory may add numeric display prefixes to physical filenames or folders where a human scan order is useful. Those prefixes are presentation only: they are not part of the logical Arco name or routing contract, and other Core files should not depend on them. Examples: ```text arco-system-manual.md arco-skills.md arco-personas.md arco-context.md ``` Core should contain behaviour that can reasonably apply across deployments. It must not contain private organisational state, organisation-specific paths, local identifiers or configuration that only makes sense in one deployment. ### Deployed operating files When a Core operating file is deployed into an organisation, it becomes a local operating copy using the corresponding `readme-*.md` convention. For example: ```text Arco Core: arco-skills.md Organisation: readme-skills.md ``` The deployed file is the **runtime source of truth** for that organisation. Runtime operation must not depend on access to the upstream Arco Core repository. Each deployed Core-derived README records the Core version from which it was established or last reconciled. A secure canonical distribution source may also be recorded for update comparison when one exists. A deployment must not expose a private authoring repository merely to provide that pointer, and runtime operation must never depend on upstream access. ### Local configuration Where a module requires deployment-specific configuration, that configuration should be isolated in a small `readme-*-local.md` companion file. For example: ```text readme-skills.md ↓ readme-skills-local.md ``` Local configuration may contain things such as: - paths; - file or register identifiers; - local storage locations; - authoritative local sources; - deployment-specific inventory. Do not create a local companion file unless local configuration is actually required. ## Singular pointers Paths, identifiers and other system references should have one authoritative home. A higher-level file should point to the next layer rather than duplicating everything beneath it. For example: ```text readme-arco-guide.md ↓ readme-skills.md ↓ readme-skills-local.md ↓ Skills Register / local paths ``` `readme-arco-guide.md` should not also contain the Skills Register identifier. This reduces reference drift and allows parts of the system to change without requiring unrelated files to be updated. ## The Arco guide Every deployment has one root-level `readme-arco-guide.md`. The Arco guide is the deployment's bounded first-hop router. It is not a catalogue, deployment manifest, manual or duplicate source of operating rules. It should contain a concise Purpose, Routes and Routing rules. Each route should use an explicit `Read when` condition or equivalent so AI loads the smallest relevant maintained sources and stops when enough context has been obtained. The guide routes to deployment-specific operating sources, including the deployed Arco definition when understanding Arco itself is relevant. It must not route to human artifacts during ordinary runtime and must not expose Updater as a normal self-update route. The guide is intentionally deployment-specific because different deployments enable different components. Construction rules belong to Deployment; there is no universal Core Arco-guide file used directly at runtime. ## Core operating structure Arco groups its maintained components into six categories. The Core repository physically mirrors these categories so architecture and filing remain aligned. ### Core architecture Core architecture defines Arco itself and the common structure the rest of the system follows. It includes: - `arco-readme.md` — the Core definition and architecture map; - [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view) — the universal standard for maintaining Arco files; - [arco-module-manual.md](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view) — the common contract inherited by all modules; - [arco-modules.md](https://drive.google.com/file/d/1GcMnF4pLmxIhPRUlrPalmdAjjTkWUOX1/view) — the module catalogue and maturity map; - [arco-design.md](https://drive.google.com/file/d/1gpksEY6NEge2Gm_ALJTEQ5l8vXlFkmfY/view) — the architectural reasoning behind important structural decisions; - `development/` — the Development runtime, containing [arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view), unresolved/resolved Development Registers and unresolved/resolved DEV records. Development is a non-module system-evolution mechanism. It is not normal runtime context. When system change is relevant, read [arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view), then only `development/dev-unresolved-register.csv`, then the relevant unresolved DEV record(s). Read resolved Development only when history, provenance, duplication, supersession or DEV-ID allocation materially requires it. [arco-design.md](https://drive.google.com/file/d/1gpksEY6NEge2Gm_ALJTEQ5l8vXlFkmfY/view) is also consult-on-demand: use it only when architectural rationale or precedent materially affects the task. ### Modules Modules separate different kinds of durable system knowledge and behaviour so that each can evolve without becoming one large instruction file. [arco-module-manual.md](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view) defines the universal contract every module inherits. Individual module READMEs define only module-specific behaviour and do not repeat the universal module contract. A deployment only needs the modules that provide real value. #### Skills Skills provide the standard and mechanism for creating, maintaining and invoking repeatable capabilities. An individual Skill can describe **how particular work is performed**; the Skills module defines the structure those capabilities follow. #### Notes Private personal working memory for unfinished observations, thoughts and follow-ups that should persist without becoming organisational truth. Notes is an Early Core module. Its reusable boundary, stable Note identity, private-by-default storage model, unresolved/resolved lifecycle and promotion boundary are established; deployment-specific intake, setup and user experience may continue to evolve through real use. #### Personas Reusable perspectives or modes of thinking. Personas influence **how AI thinks, interprets or reviews**, rather than defining a workflow. Personas is an Early Core module. Its conceptual boundary has been proven through initial deployment use, while its broader register schema, ownership and editing rules, adaptation behaviour, deployment defaults and wider deployment evidence remain unresolved. #### Context Durable personal and organisational knowledge that helps AI understand the environment in which it is operating. Context describes **what is true or useful to know**. Context is a Live Core module. Its current foundation defines Organisation, Department/Sub-department, Position and Person Context plus the Context Register; Working Context is embedded within Person rather than maintained as a separate profile. A module can be Live in Core without being enabled in a particular deployment. ### Governance Governance owns the authority model for organisational deployments. Its top-level definition is [arco-governance.md](https://drive.google.com/file/d/1JmdNUNPVJLxFbNQKYS3cJTnDPJ6hRvxb/view), with [arco-roles.md](https://drive.google.com/file/d/1FaKj8DJygVGb0MTfoyF5lOe-K7Igw4vg/view), [arco-permissions.md](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view) and [arco-approvals.md](https://drive.google.com/file/d/1-LpCSwdAQliIM6bnnUrQCl8ywk5cVGP-/view) owning the detailed Governance components. The **System Governor** is a required Arco Role for organisational deployments. **Champion** is an optional Arco Role. Neither is a standalone module. Decisions is a Draft Module. It owns the durable organisational decision domain — proposals, decisions, lifecycle/state, acknowledgement or verification where relevant, supersession, history and associated maintained records. It consumes Governance for Roles, Permissions and Approvals rather than redefining those mechanics. ### Functions Functions are bounded, invocable operations that perform a specific action on Arco or its operating environment. They do not own an independent domain of durable knowledge. Functions may be provided by Arco Core or created within a deployment at organisation, unit or other appropriate local scope. They are distinct from Modules and Skills. Classify a capability by the responsibility it owns in Arco, not merely by whether parts of its method could be reused elsewhere: an operation whose maintained purpose is to act on Arco or its runtime is a Function; a portable maintained specification for performing repeatable work is a Skill. [arco-dry-runs.md](https://drive.google.com/file/d/1Fe2PJd-IGIE5UlZmOlr0d3mThRkKbhX7/view) defines the Core Function used to test material system changes before promotion. [arco-defrag.md](https://drive.google.com/file/d/1UdSitmm8FEgmoIOC4tqGV6_ugKh7r0nk/view) defines Arco's Core architecture-maintenance Function. Completed Defrag runs are filed under `/Arco/04-functions/defrag/`. [arco-token-totter.md](https://drive.google.com/file/d/1npsqxO1lgWSQaQjeIf9MqYmHfuNh9MPf/view) defines the Core token-efficiency audit Function. It measures file and realistic route weight, proposes smallest-safe changes, and re-measures saved files after approved updates. [arco-daily-scan.md](https://drive.google.com/file/d/12N1bSquhySwvb6-sB1nv-sD8fwCqYDx4/view) defines the Core recurring-review Function. It reads configured recent sources once where practical and routes relevant findings to enabled owners while preserving each owner's authority and lifecycle. [arco-updater.md](https://drive.google.com/file/d/1MX-gzQW4wzq00B7pkSIgN95S3BCGSdyO/view) defines the Core reconciliation Function for applying approved Core changes to a supplied deployment root without hard-coding any deployment location. [arco-dev-scan.md](https://drive.google.com/file/d/1fLP7dT_2ATZTu39RO9w6tK2c2uXj9gXO/view) processes Development using one shared scan method. Every run declares `local`, `core` or `full`; local/full runs also name the exact deployment. Dev Scan run evidence is indexed only in the Core [Dev Scan Register](https://drive.google.com/file/d/1PJyOiQO-HdWN4z_xis5G_NMSI2vKM7Qg/view) using `SCA-###` IDs. One top-level invocation produces one SCA record with scan type `local`, `core` or `full`. ### Deployment Deployment covers how Arco is installed, configured, validated and maintained within a particular person, organisation or environment. [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view) defines deployment behaviour. Reusable provider/runtime compatibility overlays live under `05-deployment/runtimes/` and are deployed only where System Setup records them as relevant. Deployment configuration, onboarding and update distribution continue to develop beneath this area. ### Human artifacts Human artifacts explain or present Arco to people without forming part of normal AI operation. [arco-human-artifacts.md](https://drive.google.com/file/d/1YgQZBC4hsGWQqoByQTomiq5l69bVJZyS/view) defines the lightweight standard for explaining Arco to people, including audience, destination-led writing and comparative Dry Run validation. [arco-for-humans.md](https://drive.google.com/file/d/1V6qNojktMigKvcv7wH3Pvrnz3ZswtRYk/view) explains what Arco is and why it exists. [arco-how-to.md](https://drive.google.com/file/d/167qJW57TE6F_V0VVbjCykXXyrv_x56Bz/view) is the practical user guide: how a person uses, shapes and extends Arco in everyday work. Both are intended to form part of Arco deployment and public distribution. **Human artifacts are part of the Arco architecture but are not runtime sources. The AI guide must not route to them during normal operation, and AI should not load them as operating context unless a human explicitly asks to work with the artifact itself.** ## Deployment configuration Different deployments can use different combinations of Arco modules and governance. The system therefore needs a way to distinguish: ```text what Arco supports ``` from: ```text what this deployment has enabled ``` `readme-system-setup.md` is the deployment manifest defined by [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view). It records which selectable components are enabled and the primary AI runtime/provider for the deployment. Where a provider-specific runtime compatibility overlay is required, System Setup also records that deployed overlay so routing can load it only for the matching runtime. Runtime overlays belong to Deployment and must not redefine canonical Arco behaviour. The wider System Setup schema and automation mechanism may continue to evolve through Deployment. Do not invent configuration fields beyond the maintained Deployment standard merely because additional state could be recorded. ## Source of truth Durable Arco behaviour belongs in maintained sources of truth, not individual chat threads. Chats are working sessions. They can produce: - corrections; - decisions; - evidence; - new requirements; - improvements. But if something needs to affect future behaviour, it should be incorporated into the maintained source that owns it. Provider memory is not an Arco source of truth. An AI runtime must not rely on provider-specific memory to store or override durable information that Arco owns, including Arco operating rules, deployment behaviour, organisational Context or durable corrections to maintained Arco behaviour. Where such learning emerges in conversation, route it into the appropriate maintained Arco owner or Development. Provider memory may still support conversational continuity or preferences that Arco deliberately does not own. If provider memory overlaps or conflicts with maintained Arco state, the maintained Arco source governs. The same principle applies to organisational data. Arco does not require ordinary business information to be moved into an Arco repository. Existing systems can remain authoritative. Arco should connect to, route to or maintain appropriate representations of those sources rather than unnecessarily replacing them. ## Adaptation Arco is designed to improve through real use. Adaptation should be **evidence-driven**, not speculative. Useful evidence can include: - an explicit correction; - a workflow producing the wrong result; - a repeated friction point; - a material organisational change; - a recurring requirement; - evidence that an existing rule or process no longer reflects reality. When evidence exposes a durable improvement, change the part of the system that owns the behaviour. A generic improvement should normally flow: ```text Arco Core ↓ deployed operating copies ``` An organisation-specific improvement should remain local unless there is a deliberate decision to generalise it into Core. If nothing material has been learned, nothing needs to change. ## Design principles Arco follows these principles: 1. **Durable state lives outside chat.** Important context, capabilities and operating rules should survive individual conversations. 2. **Core is organisation-agnostic.** Reusable operating behaviour belongs in Core; private organisational state does not. 3. **Deployments are runtime-independent.** An organisation should continue operating even if the upstream Core source is unavailable. 4. **One responsibility, one source of truth.** Rules, paths and identifiers should live with the component that owns them. 5. **Load only what is relevant.** AI should receive the smallest useful context set rather than loading the whole operating system. 6. **Use existing sources of truth.** Arco should not create replacement systems merely to bring information under its own control. 7. **Local configuration stays small.** Separate deployment-specific configuration from reusable operating behaviour. 8. **Real use drives evolution.** Build from demonstrated need rather than speculative completeness. 9. **Do not build empty architecture.** A possible future requirement is not enough reason to create another module, file, register or process. 10. **Changes are traceable.** Maintained operating files are versioned and meaningful changes have history. 11. **Governance is deployment-sensitive.** A personal deployment and a large organisation should not be forced into the same approval model. 12. **Remain provider-agnostic where practical.** Arco should not unnecessarily depend on one AI model, provider or interface. 13. **Less systems, not more.** Arco should simplify how humans and AI work together rather than become another layer of administrative overhead. ## Core repository The physical `/Arco` repository mirrors the six architectural categories defined above: ```text /Arco ├── 01-architecture/ │ ├── arco-readme.md │ ├── arco-system-manual.md │ ├── arco-module-manual.md │ ├── arco-modules.md │ ├── arco-design.md │ └── development/ │ ├── arco-development.md │ ├── dev-unresolved-register.csv │ ├── dev-resolved-register.csv │ └── logs/ │ ├── unresolved/ │ └── resolved/ ├── 02-modules/ │ ├── skills/ │ ├── personas/ │ ├── context/ │ ├── notes/ │ └── Archive/ ├── 03-governance/ │ ├── arco-governance.md │ ├── arco-roles.md │ ├── arco-permissions.md │ └── arco-approvals.md ├── 04-functions/ │ ├── arco-dry-runs.md │ ├── arco-defrag.md │ ├── arco-token-totter.md │ ├── arco-sitemapper.md │ ├── arco-daily-scan.md │ ├── arco-updater.md │ ├── arco-dev-scan.md │ ├── dev-scan/ │ │ ├── dev-scan-register.csv │ │ └── reports/ │ ├── arco-dev-rec.md │ ├── defrag/ │ │ ├── arco-defrag-register.csv │ │ └── reports/ │ └── updater/ │ ├── arco-updater-register.csv │ └── reports/ ├── 05-deployment/ │ ├── arco-deployment.md │ └── runtimes/ │ └── arco-claude-runtime.md ├── 06-human-artifacts/ │ ├── arco-human-artifacts.md │ ├── arco-for-humans.md │ └── arco-how-to.md ├── 90-marketing/ │ ├── website-updater.md │ └── arco-public-core-allow-list.md └── Archive/ ``` This structure is the canonical Core filing layout. `90-marketing` is Core-adjacent authoring and publication infrastructure. It is deliberately numbered outside the deployable `01`–`06` architecture so it remains visually ordered without being mistaken for a deployment category. It must not be copied into deployments. The numeric prefixes on the six top-level category folders are structural and preserve the architectural order: `01-architecture`, `02-modules`, `03-governance`, `04-functions`, `05-deployment`, `06-human-artifacts`. Inside `01-architecture`, physical items may also use numeric display prefixes to make the intended human reading order obvious. The logical names shown above remain the canonical Arco names. Do not use the internal ordering prefix as a routing dependency. The `development/` label above is likewise the logical name even when the physical folder carries an ordering prefix. Do not leave maintained Core files loose at `/Arco` when they belong to one of these categories. Preserve stable file IDs/pointers when reorganising files. Construction of the deployment `readme-arco-guide.md` is owned by [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view); Core does not maintain a universal runtime guide file. `/Arco/Archive/Delete/` remains the manual-cleanup holding area for items that Defrag has determined are safe to delete but cannot remove directly with available tooling. Only sufficiently mature operating behaviour should be promoted into Core. Unresolved architecture, experiments and provisional ideas belong in Development until deliberately resolved. ## Public Core and private state Arco Core is intended to be distributable. An organisation's deployment is not. This creates a deliberate boundary: ```text Public / distributable Arco Core ↓ Private Organisation deployment ↓ Organisation data and state ``` Core can therefore evolve as a reusable operating system without becoming a repository for the private knowledge of organisations using it. Future external deployments are expected to receive Core updates from a machine-readable distribution source such as `arco.stoirm.co.uk`, while the editable canonical Core remains separately maintained. The distribution mechanism itself is still under development. ## Evolution Arco will continue to evolve. Version `1.0.0` establishes the foundational operating model: - reusable Core; - local deployment; - optional local configuration; - runtime independence; - modular operating sources; - deployment-specific routing; - singular pointer ownership; - evidence-driven adaptation. It does not mean that every Arco module or governance mechanism has been designed. Unresolved architecture should remain outside this README until it is sufficiently proven to become part of the operating system. [arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view) defines how Development works. The unresolved Register indexes the active pipeline; the resolved Register and resolved records preserve history outside the normal read path. [arco-modules.md](https://drive.google.com/file/d/1GcMnF4pLmxIhPRUlrPalmdAjjTkWUOX1/view) records the current module catalogue and maturity. [arco-design.md](https://drive.google.com/file/d/1gpksEY6NEge2Gm_ALJTEQ5l8vXlFkmfY/view) is Arco's architectural memory. It records **why** major architectural choices were made, including meaningful alternatives deliberately rejected or avoided, while this README remains the definition of **what Arco is and how its major parts fit together**. Canonical operating files continue to own behaviour. ## Changelog | Date | Version | Change | Approved by | Changed by | |---|---|---|---|---| | 30-Sep-2026 | 1.29.1 | Reconciled Development layout and unified local/core/full Dev Scan references; Rolled the live changelog to five entries with archived history. | Stoirm Arnold — Defrag invocation | Codex Work | | 28-Sep-2026 | 1.29.0 | Consolidated Dev Scan routing onto one parameterised arco-dev-scan Function; removed active Local/Core child Function routes. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) | | 28-Sep-2026 | 1.28.0 | Added `arco-how-to.md` as the practical human-use guide, removed retired Ideation from live Core discovery, and generalised deployment-specific Personas maturity wording. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) | | 26-Sep-2026 | 1.27.0 | Added the dedicated Development Reconciliation Function for aligning Core and deployment DEV state before implementation/update work. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) | | 26-Sep-2026 | 1.26.0 | Made the provider-memory boundary explicit: durable information owned by Arco must be stored through maintained Arco sources, provider memory may only supplement unowned conversational continuity/preferences, and maintained Arco state wins on conflict. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |