refactor(aggregation): remove docs/projects/ mirror layer and dead config

.gitignore

@@ -7,7 +7,6 @@ shell.nix
 .envrc
 
 # added by aggregation
-docs/projects
 docs/**/.media
 docs/**/_static
 docs/**/assets

Makefile

@@ -138,7 +138,6 @@ clean:
 	@echo "Cleaning build artifacts and aggregated docs..."
 	rm -rf docs/.vitepress/dist
 	rm -rf docs/.vitepress/cache
-	rm -rf docs/projects
 	@# Clean aggregated (untracked) content from section directories, preserving git-tracked files
 	@if [ -d .git ]; then \
 		git clean -fdX docs/contributing/ docs/explanation/ docs/how-to/ docs/reference/ docs/tutorials/ 2>/dev/null || true; \

docs/.vitepress/config.mts

@@ -81,7 +81,6 @@ export default defineConfig({
     // Ignore dead links in legacy documentation
     /\/how-to\/troubleshooting\//,
     /localhost/,
-    /\/projects\/gardenlinux\/02_operators\/deployment/,
     // Ignore section index links without trailing slash (VitePress internal)
     /\/tutorials\/index$/,
     /\/how-to\/index$/,

docs/.vitepress/sidebar.ts

@@ -13,7 +13,6 @@ export function generateDocumentationSidebar(): any {
     useTitleFromFrontmatter: true,
     useFolderLinkFromIndexFile: true,
     useFolderTitleFromIndexFile: true,
-    excludePattern: ['projects'],
     sortMenusByFrontmatterOrder: true,
     frontmatterOrderDefaultValue: 999,
     prefixSeparator: '/',

docs/contributing/documentation/adding-repos.md

@@ -35,7 +35,6 @@ Edit `repos-config.json` and add a new entry to the `repos` array:
   "name": "new-repo",
   "url": "https://github.com/gardenlinux/new-repo",
   "docs_path": "docs",
-  "target_path": "projects/new-repo",
   "ref": "main",
   "structure": "flat"
 }
@@ -46,49 +45,17 @@ Edit `repos-config.json` and add a new entry to the `repos` array:
 - **`name`**: Unique identifier for the repository
 - **`url`**: Git URL or `file://` path for local development
 - **`docs_path`**: Path to docs directory within the repository
-- **`target_path`**: Where to place mirrored docs (usually `projects/<name>`)
 - **`ref`**: Git branch or tag to fetch from
 
 ### Optional Fields
 
 - **`commit`**: Lock to a specific commit hash for reproducibility
 - **`root_files`**: List of root-level files to copy (e.g.,
   `["README.md", "CONTRIBUTING.md"]`)
-- **`structure`**: Directory mapping strategy (see below)
+- **`structure`**: Directory mapping strategy (`"flat"` or `"sphinx"`; see below)
 - **`media_directories`**: List of media directories to copy (e.g.,
   `[".media", "_static", "assets"]`)
 
-## Step 2: Choose a Structure Strategy
-
-### Flat Structure
-
-Copy all files as-is without reorganization:
-
-```json
-"structure": "flat"
-```
-
-### Sphinx Structure
-
-For Sphinx-generated documentation:
-
-```json
-"structure": "sphinx"
-```
-
-### Custom Mapping
-
-Map source directories to Diataxis categories:
-
-```json
-"structure": {
-  "tutorials": "tutorials",
-  "guides": "how-to",
-  "concepts": "explanation",
-  "api": "reference"
-}
-```
-
 ## Step 3: Configure Targeted Documentation
 
 To have files automatically placed into the main Diataxis structure, add
@@ -105,10 +72,29 @@ github_target_path: "docs/how-to/example-guide.md"
 Content here...
 ```
 
-Files with `github_target_path` will be copied to that exact location, not to
-`projects/<repo-name>/`.
+Files with `github_target_path` will be copied to that exact location in the
+site. Source-repo files without `github_target_path` are excluded from the
+built site entirely.
+
+## Step 2: Choose a Structure Strategy
+
+### Flat Structure
 
-## Step 4: Test with Local Configuration
+Copy all docs files as-is without reorganization:
+
+```json
+"structure": "flat"
+```
+
+### Sphinx Structure
+
+For Sphinx-generated documentation:
+
+```json
+"structure": "sphinx"
+```
+
+## Step 3: Test with Local Configuration
 
 Create or edit `repos-config.local.json` for local testing:
 
@@ -117,10 +103,7 @@ Create or edit `repos-config.local.json` for local testing:
   "repos": [
     {
       "name": "new-repo",
-      "url": "file://../new-repo",
-      "docs_path": "docs",
-      "target_path": "projects/new-repo",
-      "structure": "flat"
+      "url": "file://../new-repo"
     }
   ]
 }
@@ -132,22 +115,16 @@ Then test aggregation:
 make aggregate-local
 ```
 
-## Step 5: Verify the Output
+## Step 4: Verify the Output
 
-Check that files are in the correct locations:
-
-```bash
-ls -la docs/projects/new-repo/
-```
-
-If using `github_target_path`, verify targeted files:
+Check that targeted files landed in the correct Diataxis section:
 
 ```bash
 ls -la docs/tutorials/
 ls -la docs/how-to/
 ```
 
-## Step 6: Lock the Commit (Production)
+## Step 5: Lock the Commit (Production)
 
 For production, lock to a specific commit:
 
@@ -163,7 +140,6 @@ Or manually add the commit hash:
   "name": "new-repo",
   "url": "https://github.com/gardenlinux/new-repo",
   "docs_path": "docs",
-  "target_path": "projects/new-repo",
   "ref": "main",
   "commit": "abc123def456...",
   "structure": "flat"
@@ -204,20 +180,6 @@ Copy root-level files (like README.md or CONTRIBUTING.md):
 These files can also have `github_target_path` front-matter for targeted
 placement.
 
-### Special Files
-
-Handle non-standard files:
-
-```json
-{
-  "name": "new-repo",
-  "special_files": {
-    "GUIDE.md": "how-to",
-    "CONCEPTS.md": "explanation"
-  }
-}
-```
-
 ## Complete Example
 
 Here's a complete configuration:
@@ -227,23 +189,16 @@ Here's a complete configuration:
   "name": "example-tool",
   "url": "https://github.com/gardenlinux/example-tool",
   "docs_path": "documentation",
-  "target_path": "projects/example-tool",
   "ref": "docs-ng",
   "commit": "1234567890abcdef",
   "root_files": ["README.md"],
-  "structure": {
-    "getting-started": "tutorials",
-    "guides": "how-to",
-    "concepts": "explanation",
-    "api-reference": "reference"
-  },
-  "media_directories": [".media", "images"],
-  "special_files": {
-    "CHANGELOG.md": "reference"
-  }
+  "structure": "flat",
+  "media_directories": [".media", "images"]
 }
 ```
 
+The `docs_path` field defaults to `"docs"` and may be omitted when the documentation lives in a `docs/` directory.
+
 ## Troubleshooting
 
 ### Files Not Appearing

docs/contributing/documentation/aggregation-architecture.md

@@ -90,17 +90,16 @@ source repositories into a unified VitePress documentation site.
 
 1. **Link Rewriting:** Transform relative links to work across repository
    boundaries
-   - Intra-repo links: Maintained relative to project mirror
-   - Cross-repo links: Rewritten to absolute paths
+   - Links that escape the docs tree via `../`: Redirected to GitHub
+   - Absolute `/` links: Redirected to GitHub
+   - Relative and `./` links: Left unchanged for VitePress to resolve natively
    - External links: Preserved as-is
 
 2. **Front-matter Handling:** Ensure all documents have proper front-matter
    - Add missing front-matter blocks
    - Quote YAML values safely
    - Preserve existing metadata
 
-3. **Project Link Validation:** Fix broken links to project mirrors
-
 ### 3. Structure Stage (`structure.py`)
 
 **Purpose:** Organize documentation into the final directory structure
@@ -109,16 +108,11 @@ source repositories into a unified VitePress documentation site.
 
 1. **Targeted Documentation:** Copy files with `github_target_path` to specified
    locations
-2. **Directory Mapping:** Transform source directories according to `structure`
-   config
+2. **Internal Link Verification:** Fail aggregation if any shipped file links
+   to a source-repo file that was not itself shipped (hard-fail to catch
+   unmigrated links early)
 3. **Media Copying:** Discover and copy media directories
-4. **Markdown Processing:** Apply transformations to all markdown files
-
-**Structure Types:**
-
-- **Flat:** Copy all files as-is
-- **Sphinx:** Handle Sphinx documentation structure
-- **Custom Mapping:** Map source directories to Diataxis categories
+4. **Markdown Processing:** Apply front-matter fixes to all copied files
 
 ## Key Mechanisms
 
@@ -141,17 +135,8 @@ github_target_path: "docs/how-to/example.md"
 4. Apply markdown transformations
 
 This allows fine-grained control over where content appears in the final site.
-
-### Project Mirrors
-
-In addition to targeted docs, the entire `docs/` directory from each repo is
-mirrored under `docs/projects/<repo-name>/`:
-
-**Purpose:**
-
-- Preserve complete repository documentation
-- Provide fallback for untargeted content
-- Enable browsing of raw source structure
+All source-repo files that are not tagged with `github_target_path` are
+excluded from the built site entirely.
 
 ### Media Directory Handling
 
@@ -215,12 +200,6 @@ This fetches the latest from `ref` and updates commit locks.
 - **Testability:** Easy to test individual stages
 - **Extensibility:** New transformations added without affecting fetch/structure
 
-### Why Project Mirrors?
-
-- **Completeness:** No documentation is lost
-- **Development:** Easier to debug and understand source structure
-- **Backwards Compatibility:** Existing links to source repos still work
-
 ## Data Flow
 
 ### Repository → Temporary Directory
@@ -243,11 +222,8 @@ Temp Directory                 Docs Output
 ├── tutorials/                 docs/
 │   └── guide.md                   ├── tutorials/
 │       (github_target_path)       │   └── guide.md (targeted)
-├── how-to/                        ├── how-to/
-└── reference/                     └── projects/repo-name/
-                                       ├── tutorials/ (mirror)
-                                       ├── how-to/ (mirror)
-                                       └── reference/ (mirror)
+├── how-to/                        └── how-to/
+└── reference/                         (targeted files only)
 ```
 
 ## Performance Characteristics
@@ -265,7 +241,7 @@ Temp Directory                 Docs Output
 ### Structure Stage
 
 - **Targeted copy:** O(n) where n = files with github_target_path
-- **Directory mapping:** O(n) where n = total files
+- **Link verification:** O(n * l) where l = avg links per file
 - **Media copy:** O(m) where m = media files
 
 ### Overall