docs: Improve documentation

* docs(core-concepts): better overall documentation

* docs(case-studies): Add case study on cognitive errors in AI

* chore: Update README for clarity

- Add CLAUDE.md and .geminiignore to .gitignore
- Rename AI Persona Builder CLI to Copilot Instructions CLI in README
- Enhance README with structured sections and improved descriptions
- Update package.json with additional metadata and dependencies

* Update docs/1-getting-started/01-quickstart.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: synthable

.gitignore

@@ -139,3 +139,8 @@ vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 
 .DS_Store
+docs/archive/
+docs/evaluations/
+docs/todo.md
+CLAUDE.md
+.geminiignore

README.md

@@ -1,140 +1,195 @@
-# AI Persona Builder CLI
+# Copilot Instructions CLI
 
-A command-line interface (CLI) for building and managing AI persona instructions from modular files.
+[![NPM Version](https://img.shields.io/npm/v/instructions-composer-cli.svg)](https://www.npmjs.com/package/instructions-composer-cli)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Node.js Version](https://img.shields.io/badge/node-v22.17.1-blue.svg)](https://nodejs.org/en/)
 
-## Installation
+The Copilot Instructions CLI is a powerful command-line interface (CLI) designed to revolutionize how developers create and manage instructions for AI assistants. It shifts from monolithic, hard-to-maintain prompt files to a modular, reusable, and powerful ecosystem.
 
-```bash
-npm install -g copilot-instructions
-```
+## Table of Contents
 
-## Usage
+- [Copilot Instructions CLI](#copilot-instructions-cli)
+  - [Table of Contents](#table-of-contents)
+  - [🚀 Introduction \& Philosophy](#-introduction--philosophy)
+    - [What Problem Does It Solve?](#what-problem-does-it-solve)
+    - [How Does It Solve This?](#how-does-it-solve-this)
+    - [Who Would Use It?](#who-would-use-it)
+    - [Why Would They Use It?](#why-would-they-use-it)
+  - [Core Concepts](#core-concepts)
+    - [Modules](#modules)
+    - [Personas](#personas)
+  - [Features](#features)
+  - [Project Structure](#project-structure)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [CLI Commands](#cli-commands)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
 
-### `build <personaFile>`
+## 🚀 Introduction & Philosophy
 
-Builds a persona instruction file from a `.persona.jsonc` configuration.
+The Copilot Instructions CLI is a powerful command-line interface (CLI) designed to revolutionize how developers create and manage instructions for AI assistants. It shifts from monolithic, hard-to-maintain prompt files to a modular, reusable, and powerful ecosystem.
 
-**Arguments:**
+Our core philosophy is that a persona is a **cognitive architecture** for an AI. By carefully layering modules, you define not just _what_ the AI should do, but _how it should think_.
 
-- `personaFile`: (Required) The path to the `*.persona.jsonc` configuration file.
+- **Modular:** Build complex instruction sets from small, reusable parts.
+- **Version-Controlled:** Manage your prompts with the power of Git.
+- **Collaborative:** Share and reuse modules across projects and teams.
+- **Reliable:** Create deterministic, predictable AI behavior.
+- **Composable:** Combine modules to create sophisticated personas that can handle complex tasks.
+- **Extensible:** Add custom modules and personas to fit your specific needs.
+- **Declarative:** Use a simple, structured format to define your AI's capabilities.
 
-**Example:**
+### What Problem Does It Solve?
 
-```bash
-copilot-instructions build ./personas/my-persona.jsonc
-```
+Modern AI is incredibly powerful, but instructing it is often a chaotic and frustrating process. Developers and teams who rely on AI assistants face a critical set of problems:
 
-### `list`
+- **Inconsistency:** The same prompt can yield wildly different results, making the AI feel more like an unpredictable oracle than a reliable tool.
+- **Maintenance Nightmare:** Prompts quickly become monolithic, thousand-line text files that are brittle, impossible to debug, and terrifying to modify.
+- **Lack of Reusability:** Expert knowledge and effective instructions are trapped inside these giant prompts, leading to endless copy-pasting and duplicated effort.
+- **No Collaboration:** There is no effective way for a team to collaboratively build, manage, and version-control a shared set of AI instructions.
 
-Lists all available instruction modules.
+In short, prompt engineering today feels more like an arcane art than a disciplined engineering practice. **The Copilot Instructions CLI solves this by treating AI instructions with the same rigor and structure as we treat source code.**
 
-**Options:**
+### How Does It Solve This?
 
-- `-t, --tier <name>`: Filter the list by a specific tier (e.g., `foundation`, `principle`, `technology`, `execution`).
+The Copilot Instructions CLI deconstructs the monolithic prompt into a modular, version-controlled ecosystem. It provides a complete methodology and a command-line interface (CLI) to build powerful, specialized AI agents called "Personas."
 
-**Example:**
+This is achieved through a set of core architectural principles:
 
-```bash
-copilot-instructions list --tier=foundation
-```
+1.  **Atomic Modules:** The system is built on **Modules**—small, single-purpose Markdown files that represent one atomic concept (e.g., a reasoning skill, a coding standard, a security principle). This makes instructions reusable, testable, and easy to maintain.
+2.  **The 4-Tier System:** We enforce a strict **"waterfall of abstraction"** during compilation. Modules are organized into four tiers (`Foundation`, `Principle`, `Technology`, `Execution`), ensuring the AI's reasoning is built on a logical and predictable foundation, moving from universal truths down to specific actions.
+3.  **Structured Schemas:** Every module adheres to a specific **Schema** (`procedure`, `specification`, `pattern`, etc.). This provides a machine-readable "API" for the AI's thought process, transforming vague requests into deterministic, structured instructions.
+4.  **The Persona File:** A simple `persona.jsonc` file acts as a "recipe" or a `package.json` for your AI. It declaratively lists the modules to include, allowing you to compose, version, and share complex AI personalities with ease.
 
-### `search <query>`
+By combining these elements, the system assembles a final, optimized prompt that is not just a list of instructions, but a complete **cognitive architecture** for the AI.
 
-Searches for modules by name or description.
+### Who Would Use It?
 
-**Arguments:**
+This system is designed for anyone who wants to move beyond simple AI conversations and build reliable, professional-grade AI agents.
 
-- `query`: (Required) The text to search for.
+- **Software Development Teams:** To create a consistent "team copilot" that enforces shared coding standards, follows the team's architectural patterns, and writes code in a uniform style, regardless of which developer is prompting it.
+- **Senior Engineers & Architects:** To codify their expert knowledge and design principles into reusable modules, allowing them to scale their expertise across the entire organization.
+- **AI Power Users & Prompt Engineers:** To build and manage highly complex, multi-layered instruction sets that are simply not feasible with single-file prompts.
+- **AI Safety & Governance Teams:** To create "Auditor" personas with a provably consistent set of ethical rules and logical frameworks, enabling them to build AI agents that are aligned, predictable, and safe.
 
-**Options:**
+### Why Would They Use It?
 
-- `-t, --tier <name>`: Restrict the search to a specific tier.
+The ultimate goal of the Copilot Instructions CLI is to give you **control and reliability**. Instead of wrestling with an unpredictable AI, you can finally start engineering it.
 
-**Example:**
+Users choose this system to:
 
-````bash
-copilot-instructions search "React"
-```
+- **Achieve Consistent, High-Quality Results:** Stop gambling on your AI's output. The structured, machine-centric approach dramatically reduces randomness and produces reliable, deterministic behavior.
+- **Build a Reusable Knowledge Base:** Stop writing the same instructions over and over. Create a module once and reuse it across dozens of personas and projects.
+- **Codify and Scale Expertise:** Capture the "secret sauce" of your best engineers in a library of modules that can elevate the entire team's performance.
+- **Collaborate Effectively:** Manage your AI's instruction set as a shared, version-controlled codebase. Use pull requests to propose changes and build a collective "AI brain" for your team.
+- **Maintain and Evolve with Ease:** When a standard changes, simply update a single module, and every persona that uses it is instantly updated. This is maintainability for the AI era.
 
-### `create-module`
+The Copilot Instructions CLI is for those who believe that the power of AI should be harnessed with the discipline of engineering.
 
-Creates a new instruction module.
+## Core Concepts
 
-**Example:**
+> [!TIP]
+> To dive deeper into the project's vision, read the [**Core Concepts**](./docs/2-user-guide/01-core-concepts.md) documentation.
 
-```bash
-copilot-instructions create-module
-```
+### Modules
 
-### `create-persona`
+Modules are the building blocks of your AI's knowledge and skills. They are individual Markdown files containing specific instructions, principles, or data. Each module is a self-contained unit of knowledge that can be mixed and matched to create different AI personas.
 
-Creates a new persona configuration file.
+Modules are organized into a four-tier hierarchy:
 
-**Example:**
+- **`foundation`**: The universal, abstract truths of logic, reason, ethics, and problem-solving.
+- **`principle`**: Established, technology-agnostic best practices and methodologies.
+- **`technology`**: Specific, factual knowledge about a named tool, language, or platform.
+- **`execution`**: Imperative, step-by-step playbooks for performing a specific, concrete action.
+
+> [!TIP]
+> Learn how to create your own modules in the [**Module Authoring Guide**](./docs/3-authoring/01-module-authoring-guide.md).
+
+### Personas
+
+A persona is a collection of modules that define the behavior and capabilities of an AI assistant. Personas are defined in `.persona.jsonc` files, which specify the modules to include, the output file for the generated instructions, and other configuration options.
+
+> [!TIP]
+> Get started quickly by using pre-built [**Persona Templates**](./docs/1-getting-started/02-persona-templates.md).
+
+## Features
+
+- **Modular Architecture**: Build complex AI personas by combining reusable instruction modules.
+- **Tiered Organization**: Modules are organized into a four-tier hierarchy for logical instruction composition.
+- **Easy Scaffolding**: Quickly create new modules and persona configurations with interactive CLI commands.
+- **Validation**: Ensure the integrity of your modules and personas with built-in validation.
+- **Customizable Output**: Configure the output path and attribution settings for your built persona files.
+
+## Project Structure
 
-```bash
-copilot-instructions create-persona
+```
+.
+├── instructions-modules/
+│   ├── foundation/
+│   ├── principle/
+│   ├── technology/
+│   └── execution/
+├── personas/
+│   └── my-persona.persona.jsonc
+├── dist/
+│   └── my-persona.md
+└── ...
 ```
 
-### `validate [path]`
+- **`instructions-modules/`**: Contains the instruction modules, organized by tier.
+- **`personas/`**: Contains the persona configuration files.
+- **`dist/`**: The default output directory for built persona files.
 
-Validates all modules and persona files, or a specific file or directory.
+> [!TIP]
+> For a detailed explanation of the codebase, see the [**Project Architecture**](./docs/4-contributing/02-project-architecture.md) document.
 
-**Arguments:**
+## Prerequisites
 
-*   `path`: (Optional) The path to a specific file or directory to validate.
+- [Node.js](https://nodejs.org/) (version 22.17.1 or higher)
+- [npm](https://www.npmjs.com/) (Node Package Manager)
 
-**Examples:**
+## Installation
 
 ```bash
-# Validate all modules and personas
-copilot-instructions validate
-
-# Validate a specific module
-copilot-instructions validate ./instructions-modules/foundation/logic/if-then-statements.md
-
-# Validate a specific persona
-copilot-instructions validate ./personas/my-persona.jsonc
-````
-
-## Persona File Format
-
-A `*.persona.jsonc` file is a JSONC file that defines the composition of an AI persona.
-
-**Schema:**
-
-- `name` (string, required): A descriptive name for the persona.
-- `description` (string, optional): A brief description of the persona.
-- `output` (string, optional): The output path for the built persona file. Defaults to the persona file's name with an `.md` extension.
-- `attributions` (boolean, optional): Whether to include attribution comments for each module. Defaults to `false`.
-- `modules` (array of strings, required): An ordered list of module IDs to include.
-
-**Example:**
-
-```json
-{
-  "name": "React TDD Developer",
-  "description": "An AI assistant for developing React components using Test-Driven Development.",
-  "output": "dist/react-tdd-developer.md",
-  "attributions": true,
-  "modules": [
-    "foundation/logic/first-principles-thinking",
-    "principle/methodology/test-driven-development",
-    "technology/framework/react/rules-of-hooks",
-    "execution/playbook/write-unit-tests"
-  ]
-}
+npm install -g copilot-instructions-cli
 ```
 
-## Module System
+> [!TIP]
+> For a more detailed installation guide, see the [**Quick Start Guide**](./docs/1-getting-started/01-quickstart.md).
+
+## CLI Commands
+
+The CLI provides a set of commands for managing your modules and personas.
+
+- `build`: Builds a persona instruction file from a configuration.
+- `list`: Lists all available instruction modules.
+- `search`: Searches for modules by name or description.
+- `create-module`: Creates a new instruction module.
+- `create-persona`: Creates a new persona configuration file.
+- `validate`: Validates all modules and persona files.
+
+> [!TIP]
+> For a complete list of commands, options, and examples, see the [**CLI Reference**](./docs/2-user-guide/02-cli-reference.md).
+
+## Development
+
+This project uses `npm` for package management.
+
+- `npm install`: Install dependencies.
+- `npm run build`: Build the project.
+- `npm run test`: Run tests.
+- `npm run lint`: Lint the codebase.
+- `npm run format`: Format the codebase.
+
+## Contributing
 
-The module system is based on a four-tier hierarchy of directories within the `instructions-modules` directory.
+Contributions are welcome! Please read our [**Code of Conduct**](./docs/4-contributing/04-code-of-conduct.md) and follow the [**Governance**](./docs/4-contributing/01-governance.md) process to open an issue or submit a pull request.
 
-- **Tier:** The top-level directory (e.g., `foundation`, `principle`, `technology`, `execution`).
-- **Subject:** Subdirectories that further categorize the modules.
-- **Module File:** A Markdown file with YAML frontmatter.
+> [!TIP]
+> Before contributing, please review our [**Testing Strategy**](./docs/4-contributing/03-testing-strategy.md).
 
-**Module Frontmatter:**
+## License
 
-- `name` (string, required): A human-readable name for the module.
-- `description` (string, required): A brief description of the module.
+This project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.