fix: CLA signatures branch + declutter repo root

.claude/skills/aurelio-review-pr/SKILL.md

@@ -204,9 +204,9 @@ The **docs-consistency** agent ensures project documentation never drifts from t
 
 **What to check:**
 
-Read the current `DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing.
+Read the current `CLAUDE.md` and `README.md` in full, plus the relevant `docs/design/` pages (see `docs/DESIGN_SPEC.md` for the index). Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing.
 
-**DESIGN_SPEC.md (CRITICAL — this is the project's source of truth):**
+**Design pages in `docs/design/` (CRITICAL — these are the project's source of truth):**
 1. §15.3 Project Structure — does it match the actual files/directories under `src/ai_company/`? Any new modules missing? Any listed files that no longer exist? (CRITICAL)
 2. §3.1 Agent Identity Card — does the config/runtime split documentation match the actual model code? (MAJOR)
 3. §15.4 Key Design Decisions — are technology choices and rationale still accurate? (MAJOR)

.claude/skills/pre-pr-review/SKILL.md

@@ -306,9 +306,9 @@ The docs-consistency agent ensures project documentation never drifts from the c
 
 **What to check:**
 
-Read the current `DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing.
+Read the current `CLAUDE.md` and `README.md` in full, plus the relevant `docs/design/` pages (see `docs/DESIGN_SPEC.md` for the index). Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing.
 
-**DESIGN_SPEC.md (CRITICAL — this is the project's source of truth):**
+**Design pages in `docs/design/` (CRITICAL — these are the project's source of truth):**
 1. §15.3 Project Structure — does it match the actual files/directories under `src/ai_company/`? Any new modules missing? Any listed files that no longer exist? (CRITICAL)
 2. §3.1 Agent Identity Card — does the config/runtime split documentation match the actual model code? (MAJOR)
 3. §15.4 Key Design Decisions — are technology choices and rationale still accurate? (MAJOR)

.claude/skills/research-link/SKILL.md

@@ -24,7 +24,7 @@ Research any external content — URL, tool, concept, pasted article, code snipp
 
 ## Phase 0: Load Project Context
 
-**Before doing anything else**, read `DESIGN_SPEC.md` in the project root. This is the authoritative source for the project's architecture, module design, technology choices, and risk register. You need this context loaded to produce accurate project mappings and verdicts in later phases. Read it in parallel with the Phase 1 content acquisition.
+**Before doing anything else**, read the relevant `docs/design/` page(s) for the topic being researched (see `docs/DESIGN_SPEC.md` for the index of all design pages). These are the authoritative source for the project's architecture, module design, technology choices, and risk register. You need this context loaded to produce accurate project mappings and verdicts in later phases. Read in parallel with the Phase 1 content acquisition.
 
 ## Phase 1: Identify Input Type and Acquire Content
 

.claude/skills/worktree/SKILL.md

@@ -184,7 +184,7 @@ Directory suffix is auto-derived from the branch name:
    - #<N>: <title>
 
    ## Instructions
-   1. Read `DESIGN_SPEC.md` sections: <list relevant §sections from issue bodies>
+   1. Read the relevant `docs/design/` pages: <list pages matched from issue spec labels and §section references>
    2. Read the GitHub issues: <gh issue view commands>
    3. Read the relevant source modules: <list directories/files matched from spec labels + dependency parsing>
 

CLA.md → .github/CLA.md

@@ -100,7 +100,7 @@ or include Your Contributions in the Project.
 When you open your first pull request to SynthOrg, a bot will comment asking
 you to sign this CLA. To sign, reply to the bot's comment with the exact text
 it specifies. Your signature is stored in this repository at
-`.github/cla-signatures.json`.
+`.github/cla-signatures.json` on the `cla-signatures` branch.
 
 You only need to sign once — the agreement covers all future contributions.
 

.github/CONTRIBUTING.md

@@ -146,7 +146,7 @@ This project is licensed under [BUSL-1.1](../LICENSE) (Business Source License 1
 
 ### Contributor License Agreement
 
-Before your first contribution can be merged, you must sign the [Contributor License Agreement (CLA)](../CLA.md). This is required to enable dual-licensing (BSL + commercial licenses for enterprise customers).
+Before your first contribution can be merged, you must sign the [Contributor License Agreement (CLA)](CLA.md). This is required to enable dual-licensing (BSL + commercial licenses for enterprise customers).
 
 **How to sign:** When you open your first pull request, a bot will post a comment asking you to sign. Simply reply with the text specified in the comment — no forms, no external services. Your signature is recorded as a JSON entry in this repository.
 

.github/workflows/cla.yml

@@ -29,10 +29,10 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           path-to-signatures: .github/cla-signatures.json
-          path-to-document: CLA.md
-          branch: main
+          path-to-document: .github/CLA.md
+          branch: cla-signatures
           custom-notsigned-prcomment: |
-            Thank you for your contribution! Before we can merge this PR, you need to sign the [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/CLA.md).
+            Thank you for your contribution! Before we can merge this PR, you need to sign the [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/.github/CLA.md).
 
             **To sign**, please reply to this comment with the following exact text:
 

.github/workflows/zizmor.yml

@@ -6,13 +6,13 @@ on:
     paths:
       - ".github/workflows/**"
       - ".github/dependabot.yml"
-      - ".zizmor.yml"
+      - ".github/.zizmor.yml"
   pull_request:
     branches: [main]
     paths:
       - ".github/workflows/**"
       - ".github/dependabot.yml"
-      - ".zizmor.yml"
+      - ".github/.zizmor.yml"
   workflow_dispatch:
 
 permissions: {}
@@ -33,5 +33,5 @@ jobs:
       - name: Run zizmor
         uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2
         with:
-          config: .zizmor.yml
+          config: .github/.zizmor.yml
           advanced-security: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}

CLAUDE.md

@@ -6,11 +6,11 @@
 - **Python**: 3.14+ (PEP 649 native lazy annotations)
 - **License**: BUSL-1.1 with narrowed Additional Use Grant (free production use for non-competing small orgs; converts to Apache 2.0 three years after release)
 - **Layout**: `src/ai_company/` (src layout), `tests/` (unit/integration/e2e), `web/` (Vue 3 dashboard), `cli/` (Go CLI binary)
-- **Design**: [DESIGN_SPEC.md](DESIGN_SPEC.md) (pointer to `docs/design/` pages)
+- **Design**: [DESIGN_SPEC.md](docs/DESIGN_SPEC.md) (pointer to `docs/design/` pages)
 
 ## Design Spec (MANDATORY)
 
-- **ALWAYS read the relevant `docs/design/` page** before implementing any feature or planning any issue. [DESIGN_SPEC.md](DESIGN_SPEC.md) is a pointer file linking to the 7 design pages.
+- **ALWAYS read the relevant `docs/design/` page** before implementing any feature or planning any issue. [DESIGN_SPEC.md](docs/DESIGN_SPEC.md) is a pointer file linking to the 7 design pages.
 - The design spec is the **starting point** for architecture, data models, and behavior
 - If implementation deviates from the spec (better approach found, scope evolved, etc.), **alert the user and explain why** — user decides whether to proceed or update the spec
 - Do NOT silently diverge — every deviation needs explicit user approval
@@ -262,7 +262,7 @@ cli/                # Go CLI binary (cross-platform, manages Docker lifecycle)
 - **OSSF Scorecard**: `.github/workflows/scorecard.yml` — supply chain maturity scoring on push to main + weekly schedule. SARIF upload to Security tab. Contributes to OpenSSF ecosystem data via `publish_results: true`.
 - **DAST**: `.github/workflows/dast.yml` — ZAP API scan against the backend OpenAPI spec on push to main + weekly schedule. Builds backend image locally, starts container, runs ZAP. Results available as workflow artifacts (no SARIF — action v0.10.0 lacks native SARIF output). Not on PRs (too slow).
 - **Socket.dev**: GitHub App — supply chain attack detection on PRs (typosquatting, malware, suspicious ownership changes, obfuscated code). No config file needed, auto-comments on PRs.
-- **CLA**: `.github/workflows/cla.yml` — Contributor License Agreement signature check on PRs via `contributor-assistant/github-action`. Triggers on `pull_request_target` and `issue_comment`. Skips Dependabot. Signatures stored in `.github/cla-signatures.json`.
+- **CLA**: `.github/workflows/cla.yml` — Contributor License Agreement signature check on PRs via `contributor-assistant/github-action`. Triggers on `pull_request_target` and `issue_comment`. Skips Dependabot. Signatures stored in `.github/cla-signatures.json` on the `cla-signatures` branch (unprotected, so the action can commit directly).
 - **Release**: `.github/workflows/release.yml` — Release Please (Google) auto-creates a release PR on every push to main. Merging the release PR creates a git tag (`vX.Y.Z`) + GitHub Release with changelog. Tag push triggers the Docker workflow to build version-tagged images. Uses `RELEASE_PLEASE_TOKEN` secret (PAT/GitHub App token) so tag creation triggers downstream workflows (GITHUB_TOKEN cannot). Config in `.github/release-please-config.json` and `.github/.release-please-manifest.json`. After creating/updating a release PR, auto-updates the BSL Change Date in LICENSE to 3 years ahead.
 
 ## Dependencies

README.md

@@ -147,7 +147,7 @@ graph TB
 | [Developer Setup](docs/getting_started.md) | Clone, test, lint, contribute |
 | [User Guide](docs/user_guide.md) | Install, configure, run via Docker |
 
-> **Contributors:** Start with the [Design Overview](docs/design/index.md) before implementing any feature — it is the mandatory starting point for architecture, data models, and behavior. [`DESIGN_SPEC.md`](DESIGN_SPEC.md) serves as a pointer to the full design set.
+> **Contributors:** Start with the [Design Overview](docs/design/index.md) before implementing any feature — it is the mandatory starting point for architecture, data models, and behavior. [`DESIGN_SPEC.md`](docs/DESIGN_SPEC.md) serves as a pointer to the full design set.
 
 ## Status
 

docs/getting_started.md

@@ -124,7 +124,7 @@ synthorg/
   web/                  # Vue 3 web dashboard (PrimeVue + Tailwind CSS)
   .github/              # CI workflows, dependabot, actions
   pyproject.toml        # Project config (deps, tools, linters)
-  DESIGN_SPEC.md        # Pointer to design specification pages
+  docs/DESIGN_SPEC.md   # Pointer to design specification pages
   CLAUDE.md             # AI assistant quick reference
 ```
 

docs/licensing.md

@@ -11,7 +11,7 @@
 | Production use by large org (500+ employees and contractors) | Conditional | Commercial license |
 | Offering SynthOrg as a hosted/managed service | Conditional | Commercial license |
 | Reselling or embedding SynthOrg as your core product | Conditional | Commercial license |
-| Contributing to SynthOrg | Yes | Sign the [CLA](https://github.com/Aureliolo/synthorg/blob/main/CLA.md) |
+| Contributing to SynthOrg | Yes | Sign the [CLA](https://github.com/Aureliolo/synthorg/blob/main/.github/CLA.md) |
 
 *"Conditional" uses require a commercial license — please [contact us](https://github.com/Aureliolo/synthorg/discussions) to discuss terms.*
 
@@ -111,7 +111,7 @@ This means:
 
 ## Contributor License Agreement (CLA)
 
-We require a [Contributor License Agreement](https://github.com/Aureliolo/synthorg/blob/main/CLA.md) before merging external contributions. The CLA:
+We require a [Contributor License Agreement](https://github.com/Aureliolo/synthorg/blob/main/.github/CLA.md) before merging external contributions. The CLA:
 
 - Grants SynthOrg a non-exclusive license to your contributions
 - **Does not transfer ownership** — you retain full rights to your work