refactor(root): move root artefacts to their canonical locations

.github/CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Clone the repository
+
+git clone <https://github.com/hyperpolymath/nextgen-databases.git> cd
+nextgen-databases
+
+# Using Nix (recommended for reproducibility)
+
+nix develop
+
+# Or using toolbox/distrobox
+
+toolbox create nextgen-databases-dev toolbox enter nextgen-databases-dev
+\# Install dependencies manually
+
+# Verify setup
+
+just check \# or: cargo check / mix compile / etc. just test \# Run test
+suite
+
+
+    ### Repository Structure
+
+    `nextgen-databases` is a **coordination repo** — it does not hold database
+    implementations. Each database and query language has its own repo (see `REGISTRY.adoc`).
+
+nextgen-databases/ ├── README.adoc / EXPLAINME.adoc / TOPOLOGY.adoc /
+ROADMAP.adoc \# Portfolio docs ├── REGISTRY.adoc \# Authoritative map:
+database/language → its own repo ├── CLAUDE.md / AGENTS.md /
+0-AI-MANIFEST.a2ml \# Agent guardrails ├── docs/ \# Coordination docs
+(incl. migration runbooks) ├── tests/ \# CROSS-database integration
+tests only ├── .machine_readable/ \# Canonical SCM metadata ├── .github/
+\# CI/CD, issue templates, governance ├── .well-known/ LICENSES/ └──
+flake.nix / Justfile / stapeln.toml / opsm.toml \# Shared env &
+orchestration
+
+
+    #### What belongs here vs. in a database repo
+
+    - ✅ **Here**: portfolio docs, the registry, cross-database integration tests, shared
+      infrastructure/orchestration, governance and machine-readable metadata.
+    - ❌ **Not here — use the database's own repo**: per-database source code, schemas,
+      migrations, storage engines, query-language implementations, per-database design docs,
+      whitepapers, benchmarks, and datasets. See `REGISTRY.adoc` for the destination repo.
+
+    A CI guard (`.github/workflows/placement-guard.yml`) and a local pre-write hook
+    (`.claude/hooks/block-db-writes.sh`) enforce this.
+
+    ---
+
+    ## How to Contribute
+
+    ### Reporting Bugs
+
+    **Before reporting**:
+    1. Search existing issues
+    2. Check if it's already fixed in `main`
+    3. Determine which perimeter the bug affects
+
+    **When reporting**:
+
+    Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include:
+
+    - Clear, descriptive title
+    - Environment details (OS, versions, toolchain)
+    - Steps to reproduce
+    - Expected vs actual behaviour
+    - Logs, screenshots, or minimal reproduction
+
+    ### Suggesting Features
+
+    **Before suggesting**:
+    1. Check the [roadmap](ROADMAP.md) if available
+    2. Search existing issues and discussions
+    3. Consider which perimeter the feature belongs to
+
+    **When suggesting**:
+
+    Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include:
+
+    - Problem statement (what pain point does this solve?)
+    - Proposed solution
+    - Alternatives considered
+    - Which perimeter this affects
+
+    ### Your First Contribution
+
+    Look for issues labelled:
+
+    - [`good first issue`](https://github.com/hyperpolymath/nextgen-databases/labels/good%20first%20issue) — Simple Perimeter 3 tasks
+    - [`help wanted`](https://github.com/hyperpolymath/nextgen-databases/labels/help%20wanted) — Community help needed
+    - [`documentation`](https://github.com/hyperpolymath/nextgen-databases/labels/documentation) — Docs improvements
+    - [`perimeter-3`](https://github.com/hyperpolymath/nextgen-databases/labels/perimeter-3) — Community sandbox scope
+
+    ---
+
+    ## Development Workflow
+
+    ### Branch Naming
+
+docs/short-description \# Documentation (P3) test/what-added \# Test
+additions (P3) feat/short-description \# New features (P2)
+fix/issue-number-description \# Bug fixes (P2) refactor/what-changed \#
+Code improvements (P2) security/what-fixed \# Security fixes (P1-2)
+
+
+    ### Commit Messages
+
+    We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+():
+
+\[optional body\]
+
+\[optional footer\]

.github/workflows/dogfood-gate.yml

@@ -44,12 +44,12 @@ jobs:
         # In-repo validator. hyperpolymath/a2ml-validate-action does not exist —
         # `gh api repos/...` returns 404 and the job failed at "Set up job" with
         # "Unable to resolve action ..., repository not found", so it never ran.
-        # .githooks/validate-a2ml.sh is the canonical RSR implementation (identical
+        # .github/hooks/validate-a2ml.sh is the canonical RSR implementation (identical
         # to the copy in rsr-template-repo) and takes the same INPUT_* interface.
         env:
           INPUT_PATH: '.'
           INPUT_STRICT: 'false'
-        run: bash .githooks/validate-a2ml.sh
+        run: bash .github/hooks/validate-a2ml.sh
 
       - name: Write summary
         run: |
@@ -98,7 +98,7 @@ jobs:
         env:
           INPUT_PATH: '.'
           INPUT_STRICT: 'false'
-        run: bash .githooks/validate-k9.sh
+        run: bash .github/hooks/validate-k9.sh
 
       - name: Write summary
         run: |

.github/workflows/placement-guard.yml

@@ -55,12 +55,12 @@ jobs:
 
           # Allowed coordination paths (regex, anchored at repo root).
           ALLOW='^(README|EXPLAINME|TOPOLOGY|ROADMAP|TOOLING-STATUS|REGISTRY|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|MAINTAINERS|NOTICE|LICENSE|PROOF-NEEDS|TEST-NEEDS|QUICKSTART-[A-Z]+|0-AI-MANIFEST|CLAUDE|GEMINI|AGENTS|llm-warmup-[a-z]+)\.[A-Za-z0-9]+$'
-          # `.githooks` added 2026-07-27. It is repo infrastructure, not database
+          # `.github/hooks` added 2026-07-27. It is repo infrastructure, not database
           # content — git resolves core.hooksPath relative to the worktree root,
           # so it must live there, exactly like .github/ and .claude/ which were
           # already allowed.
           #
-          # This became load-bearing when #59 landed .githooks/validate-a2ml.sh and
+          # This became load-bearing when #59 landed .github/hooks/validate-a2ml.sh and
           # validate-k9.sh: those files are tracked on main today, so the next PR
           # touching either one is flagged "Misplaced content" and fails the guard.
           #

CLAUDE.md

@@ -29,7 +29,7 @@ own repo.
 3. **Cross-database** integration tests (`tests/`) and shared infrastructure
    (`flake.nix`, `Justfile`, `stapeln.toml`, `opsm.toml`).
 4. **Governance & metadata**: `.github/`, `.machine_readable/`, `.well-known/`,
-   `LICENSES/`, `CONTRIBUTING.adoc`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`.
+   `LICENSES/`, `.github/CONTRIBUTING.md`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`.
 
 ### Where database content goes
 

QUICKSTART-MAINTAINER.adoc

@@ -31,7 +31,7 @@ Output: `{{BUILD_OUTPUT_PATH}}`
 
 [source,bash]
 ----
-guix build -f guix.scm
+guix build -f build/guix.scm
 ----
 
 === Nix

REGISTRY.adoc

@@ -83,7 +83,7 @@ were removed once each extraction completed (2026-07-27 and 2026-08-03).
 * Cross-database integration tests (`tests/`)
 * Shared infra & environment (`flake.nix`, `guix.scm`, `Justfile`, `stapeln.toml`, `opsm.toml`)
 * Governance & metadata (`.github/`, `.machine_readable/`, `.well-known/`, `LICENSES/`,
-  `CONTRIBUTING.adoc`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`)
+  `.github/CONTRIBUTING.md`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`)
 
 [NOTE]
 ====

SECURITY.adoc

@@ -395,7 +395,7 @@ When using Nextgen Databases, we recommend:
 * https://github.com/hyperpolymath/nextgen-databases/security/advisories[Security
 Advisories]
 * link:CHANGELOG.md[Changelog]
-* link:CONTRIBUTING.adoc[Contributing Guidelines]
+* link:.github/CONTRIBUTING.md[Contributing Guidelines]
 * https://cve.mitre.org/[CVE Database]
 * https://www.first.org/cvss/calculator/3.1[CVSS Calculator]
 

docs/accessibility/README.adoc

@@ -243,7 +243,7 @@ Burble is committed to:
 * Supporting screen readers and other assistive technologies
 * Continuous improvement based on user feedback
 
-We welcome contributions to improve accessibility. See our link:../CONTRIBUTING.adoc[Contributing Guide] for details.
+We welcome contributions to improve accessibility. See our link:../../.github/CONTRIBUTING.md[Contributing Guide] for details.
 
 == Related Documents