docs: update documentation structure and workflow references (#18)

* docs: update documentation structure and workflow references

Reorganize documentation to reflect current repository state:

- Move docs/quickstart.md to docs/README.md for better discoverability
- Delete redundant docs/index.md
- Update CLAUDE.md with accurate repository structure
- Document new codebase-agent.yml workflow and automation scripts
- Update all cross-references to new doc paths in README and PRESENTATION

Changes to CLAUDE.md:
- Add .github/scripts/codebase_agent/ automation module
- Document all 5 GitHub Actions workflows (was 2)
- Update docs/ structure to reflect standalone patterns approach
- Remove references to deleted architecture.md, tutorial.md, api-reference.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix: update CI to check for new documentation structure

Update ci.yml to check for docs/README.md instead of docs/quickstart.md
and remove check for deleted docs/index.md. Add check for docs/adr/.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: jeremyeder

.github/workflows/ci.yml

@@ -18,6 +18,6 @@ jobs:
         run: |
           # Verify patterns documentation exists
           test -d docs/patterns || { echo "Error: docs/patterns/ missing"; exit 1; }
-          test -f docs/quickstart.md || { echo "Error: docs/quickstart.md missing"; exit 1; }
-          test -f docs/index.md || { echo "Error: docs/index.md missing"; exit 1; }
+          test -f docs/README.md || { echo "Error: docs/README.md missing"; exit 1; }
+          test -d docs/adr || { echo "Error: docs/adr/ missing"; exit 1; }
           echo "All required documentation files present"

CLAUDE.md

@@ -36,10 +36,9 @@ This is a **GitHub template repository** demonstrating AI-assisted development b
 
 **Documentation** (`docs/`):
 
-- Quickstart guides for AI-assisted development
-- Architecture pattern references
-- Tutorial outlines for implementing agentic workflows
-- API design patterns
+- Quickstart guide (README.md) for AI-assisted development
+- Standalone pattern documentation (patterns/)
+- ADR scaffolding (adr/)
 
 **Codebase Agent Configuration** (`.claude/`):
 
@@ -49,9 +48,16 @@ This is a **GitHub template repository** demonstrating AI-assisted development b
 
 **CI/CD** (`.github/workflows/`):
 
-- Documentation validation workflows
-- Markdown linting
-- Mermaid diagram validation
+- Codebase Agent automation (codebase-agent.yml)
+- Documentation validation (docs-validation.yml)
+- Security scanning (security.yml)
+- Documentation deployment (deploy-docs.yml)
+
+**Automation Scripts** (`.github/scripts/codebase_agent/`):
+
+- Python module for CBA workflow execution
+- AI client with Vertex AI and Anthropic API support
+- GitHub event parsing and PR automation
 
 ### Working Application Demo
 
@@ -131,10 +137,9 @@ markdownlint docs/**/*.md README.md CLAUDE.md --fix
 
 **Core docs** (`docs/`):
 
-1. `quickstart.md` - 5-minute introduction to AI-assisted development
-2. `architecture.md` - Common architecture patterns for agentic workflows
-3. `tutorial.md` - Step-by-step guide for implementing patterns
-4. `api-reference.md` - API design patterns for AI-assisted apps
+1. `README.md` - 5-minute quickstart for AI-assisted development patterns
+2. `patterns/` - Individual pattern documentation (standalone, independently adoptable)
+3. `adr/` - Architecture Decision Records scaffolding (template only)
 
 ### Mermaid Diagrams (CRITICAL)
 
@@ -276,17 +281,31 @@ Focus on "why" rather than "what".
 
 **Workflows**:
 
-1. **`.github/workflows/docs-validation.yml`** (Documentation)
+1. **`.github/workflows/codebase-agent.yml`** (Codebase Agent)
+   - Issue-to-PR automation
+   - PR review automation
+   - Triggered by: @cba mentions, cba-review/cba-help labels
+   - Supports both Anthropic API and Vertex AI authentication
+
+2. **`.github/workflows/docs-validation.yml`** (Documentation)
    - Markdown linting (markdownlint)
    - Mermaid diagram validation
    - Link checking
    - Triggers: on docs/** changes, PRs
 
-2. **`.github/workflows/ci.yml`** (General CI)
+3. **`.github/workflows/ci.yml`** (General CI)
    - Code example linting (if any)
    - Documentation build test
    - Triggers: on push, PR
 
+4. **`.github/workflows/deploy-docs.yml`** (Documentation Deployment)
+   - Deploys documentation to GitHub Pages
+   - Triggers: on main branch push
+
+5. **`.github/workflows/security.yml`** (Security Scanning)
+   - Security vulnerability scanning
+   - Triggers: on push, PR, schedule
+
 ### Dependabot
 
 **File**: `.github/dependabot.yml`

PRESENTATION-ambient-code-reference.md

@@ -638,7 +638,7 @@ cd reference
 # Explore the patterns
 cat .claude/agents/codebase-agent.md
 cat .claude/context/architecture.md
-cat docs/quickstart.md
+cat docs/README.md
 
 # Copy to your project
 #commented out on purpose cp -r .claude /path/to/your/project/

README.md

@@ -17,7 +17,7 @@ AI-assisted development patterns. Each pattern is standalone - adopt what you ne
 
 ## Getting Started
 
-See [Quickstart](docs/quickstart.md) for pattern overview and adoption guidance.
+See [Quickstart](docs/README.md) for pattern overview and adoption guidance.
 
 ## Development Setup
 
@@ -40,7 +40,7 @@ npm install -g markdownlint-cli @mermaid-js/mermaid-cli
 ```text
 reference/
 ├── docs/
-│   ├── quickstart.md          # Pattern overview and adoption path
+│   ├── README.md              # Quickstart guide
 │   └── patterns/              # Individual pattern docs
 ├── .claude/                   # Example CBA configuration
 ├── PRESENTATION-ambient-code-reference.md  # 9-feature overview