new

README.md

@@ -1,4 +1,4 @@
-# Abstract Base Cloud
+# Introduction
 
 The ABC Pattern is a universal architectural model for structuring cloud
 infrastructure in a way that is predictable, explicit, and safe for automated
@@ -18,9 +18,9 @@ At its core, ABC is built on three foundational ideas:
 **1. A strict hierarchical structure**
 Every ABC architecture is composed of three construct types:
 
-* ApplicationStack — the root of the system
-* Logical Units — functional domains
-* Resource Groups — cohesive clusters of cloud resources
+* ApplicationStack - the root of the system
+* Logical Units - functional domains
+* Resource Groups - cohesive clusters of cloud resources
 
 This hierarchy forms a strict tree with no lateral references, ensuring clarity
 and isolation.
@@ -34,8 +34,8 @@ Every construct defines:
 
 Data flows only in two directions:
 
-* Capturing Down — parents pass data to children
-* Bubbling Up — children return data to parents
+* Capturing Down - parents pass data to children
+* Bubbling Up - children return data to parents
 
 This eliminates hidden dependencies and makes the architecture fully analyzable.
 
@@ -75,11 +75,124 @@ ABC replaces this with a model that is:
 It is designed to be understood by humans, validated by tools, and generated by
 agents.
 
-## Content
+## Contents
 
 * [Concepts](concepts.md)
 * [Abstract Model](model.md)
-* [Rules](rules/index.md)
+* [Rules](rules/README.md)
 * [Schema](schema.md)
 * [Canonical Example](example.md)
-* [Profiles](profiles/index.md)
+* [Profiles](profiles/README.md)
+
+## Usage
+
+The Abstract Base Cloud Specification is written for both human engineers and
+automated agents. It provides a clear, explicit architectural model that people
+can read, understand, and apply directly, while also offering the structure and
+determinism that agent‑driven tools require.
+
+### Manual
+
+Familarize yourself with one of the specification’s implementation profiles.
+
+### Agent-driven
+
+The specification is designed to be consumed directly by agent‑driven tools
+compatible with [AGENTS.md](https://agents.md).  It can be referenced either
+locally (via Git submodule) or remotely (via the hosted version).  Both
+approaches expose the same structure:
+
+* `README.md` - the entrypoint of the specification
+* `AGENTS.md` - operational guidance for LLM agents
+
+Your own project’s `AGENTS.md` should reference the specification’s
+`AGENTS.md` directly, so your agents always operate with the canonical rules
+and behaviors.
+
+#### IMPORTANT
+Implementation profiles of the specification only pose minor coding
+guidelines. You are responsible for setting broader rules for managing your
+repository and codebase.
+
+#### Using the Specification as a Git Submodule
+
+You can embed the specification directly into your repository:
+
+``bash
+git submodule add https://bitbucket.org/byteb4rb1e/abc-ai.git vendor/abc-ai
+``
+
+This makes the spec available locally at `./vendor/abc-ai/`.
+
+Your agents can now reference the spec’s entrypoint and agent guide via relative
+paths:
+
+* `./vendor/abc-ai/README.md`
+* `./vendor/abc-ai/AGENTS.md`
+
+This is the recommended approach for offline, air‑gapped, or privacy‑sensitive
+environments.
+
+#### Using the Hosted Specification
+
+If you prefer not to vendor the spec, you can reference the hosted version:
+
+Entry point:
+[https://spec.tiararodney.com/abc/markdown/README.md](https://spec.tiararodney.com/abc/markdown/README.md)
+
+Agent guide:
+[https://spec.tiararodney.com/abc/markdown/AGENTS.md](https://spec.tiararodney.com/abc/markdown/AGENTS.md)
+
+Agents can fetch these URLs directly when resolving rules, profiles, or schema
+definitions.
+
+#### Referencing the Specification from Your Own AGENTS.md
+
+Your project’s AGENTS.md should explicitly instruct agents to load and follow
+the ABC specification. A typical integration looks like this:
+
+#### IMPORTANT
+You MUST specify an ABC implementation profile in your `AGENTS.md`.
+
+```markdown
+# Agent Guide for This Project
+
+This project uses the **Abstract Base Cloud (ABC)** pattern with the
+Typescript CDK implementation profile for all architecture generation,
+validation, and transformation.
+
+Agents MUST follow the official ABC Specification and its agent guide:
+
+* Specification entrypoint: `./vendor/abc-ai/README.md`
+  (or the hosted version if not using a submodule)
+* Agent instructions: `./vendor/abc-ai/AGENTS.md`
+
+Agents MUST treat the ABC Specification as authoritative for authoring
+Infrastructure-as-Code.
+
+When generating infrastructure code, agents MUST:
+
+1. Load the ABC Specification’s `AGENTS.md`.
+2. Apply the rules and behaviors defined there.
+3. Use the implementation profile appropriate for the target IaC tool.
+4. Validate all generated output against the ABC Schema.
+```
+
+## License
+
+The Abstract Base Cloud Specification is licensed under the
+Creative Commons Attribution–NoDerivatives 4.0 International License (CC‑BY‑ND 4.0).
+
+You are free to:
+
+* copy and redistribute the specification in any medium or format
+* use it for commercial or non‑commercial purposes
+
+Under the following terms:
+
+* Attribution — You must give appropriate credit and provide a link to the
+  license.
+* No Derivatives — If you remix, transform, or build upon the material, you may
+  not distribute the modified specification.
+
+See the full license text in [LICENSE](LICENSE).