docs: add tutorial and howto for docs-ng

.gitignore

@@ -36,4 +36,5 @@ docs/reference/supporting_tools/**
 docs/tutorials/**
 !docs/tutorials/documentation/
 !docs/tutorials/documentation/**
+!docs/tutorials/documentation.md
 !docs/tutorials/index.md

docs/how-to/documentation/working-locally.md

@@ -0,0 +1,162 @@
+---
+title: "Contributing to the Garden Linux Documentation"
+description: "Learn how to contribute to Garden Linux documentation — working with the aggregation system locally"
+---
+
+# Contributing to the Garden Linux Documentation
+
+Garden Linux documentation is published at **https://gardenlinux-docs.netlify.app/** and combines content from multiple repositories into a unified documentation site.
+
+> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
+
+## Working with the Documentation System Locally
+
+For more substantial changes — like adding new pages, restructuring content, or working on the aggregation system itself — you'll want to set up the documentation system locally.
+
+### Prerequisites
+
+- Python 3.x
+- pnpm (for VitePress)
+- Git
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/gardenlinux/docs-ng.git
+cd docs-ng
+```
+
+### Step 2: Install Dependencies
+
+```bash
+pnpm install
+```
+
+This installs VitePress and other Node.js dependencies needed to build the documentation site.
+
+### Step 3: Aggregate Documentation
+
+#### From Remote Repositories (Production)
+
+Aggregate from locked commits in `repos-config.json`:
+
+```bash
+make aggregate
+```
+
+This fetches documentation from the configured repositories at their locked commit hashes.
+
+#### From Local Repositories (Development)
+
+For local development, use `repos-config.local.json` with `file://` URLs:
+
+```bash
+make aggregate-local
+```
+
+This copies documentation from local repositories without using git.
+
+### Step 4: Start the Development Server
+
+```bash
+make dev
+```
+
+The documentation site will be available at `http://localhost:5173`.
+
+### Step 5: Make Changes
+
+As you work on documentation in source repositories:
+
+1. Make changes to markdown files in source repos
+2. Run `make aggregate-local` to update the aggregated docs
+3. The dev server will hot-reload automatically
+
+### Step 6: Build for Production
+
+When ready to deploy:
+
+```bash
+make build
+```
+
+This creates a production build in `docs/.vitepress/dist/`.
+
+## Common Workflows
+
+### Updating a Single Repository
+
+```bash
+make aggregate-repo REPO=gardenlinux
+```
+
+### Updating Lock Files
+
+To fetch the latest commits and update `repos-config.json`:
+
+```bash
+make aggregate-update
+```
+
+### Running Tests
+
+```bash
+make test
+```
+
+## Project Structure
+
+After aggregation, your docs directory will look like:
+
+```
+docs/
+├── projects/              # Mirrored repository docs
+│   ├── gardenlinux/
+│   ├── builder/
+│   └── python-gardenlinux-lib/
+├── tutorials/             # Aggregated tutorials
+├── how-to/                # Aggregated guides
+├── explanation/           # Aggregated explanations
+├── reference/             # Aggregated reference
+└── contributing/          # Aggregated contributing docs
+```
+
+## Next Steps
+
+- Learn how to [add new repositories](../../how-to/documentation/adding-repos)
+- Understand the [architecture](../../explanation/architecture)
+- Review the [configuration reference](../../reference/documentation/configuration)
+
+## Troubleshooting
+
+### Clean Build
+
+If you encounter issues, try a clean build:
+
+```bash
+make clean
+make aggregate
+make dev
+```
+
+### Check Dependencies
+
+Ensure all dependencies are installed:
+
+```bash
+pnpm install
+python3 --version  # Should be 3.x
+```
+
+### Verify Configuration
+
+Check that `repos-config.json` or `repos-config.local.json` is properly configured. See the [configuration reference](../../reference/documentation/configuration) for details.
+
+## See Also
+
+- [Quick Edits](../../tutorials/documentation.md)
+- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
+- [Testing Reference](../../reference/documentation/testing.md) — Test suite documentation
+- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos
+- [Technical Reference](../../reference/documentation/technical.md) — Source code documentation
+- [Architecture](../../explanation/documentation/aggregation-architecture.md) — System design

docs/overview/index.md

@@ -10,14 +10,14 @@ Garden Linux documentation uses the [Diátaxis framework](https://diataxis.fr/)
 
 ## Where to Start
 
-| Your Situation | Where to Go |
-| --- | --- |
-| New to Garden Linux | Start with [Tutorials](/tutorials/) |
+| Your Situation                | Where to Go                                                  |
+| ----------------------------- | ------------------------------------------------------------ |
+| New to Garden Linux           | Start with [Tutorials](/tutorials/)                          |
 | Deploy on a specific platform | Go to [Platform-Specific Guides](/how-to/platform-specific/) |
-| Customize Garden Linux | Check [Customization Guides](/how-to/customization/) |
-| Understand concepts | Read [Explanation](/explanation/) |
-| Look up specifications | Search [Reference](/reference/) |
-| Contribute to the project | See [Contributing](/contributing/) |
+| Customize Garden Linux        | Check [Customization Guides](/how-to/customization/)         |
+| Understand concepts           | Read [Explanation](/explanation/)                            |
+| Look up specifications        | Search [Reference](/reference/)                              |
+| Contribute to the project     | See [Contributing](/contributing/)                           |
 
 ## Tutorials
 

docs/reference/documentation/configuration.md

@@ -299,6 +299,8 @@ These help create source links in the documentation.
 
 ## See Also
 
+- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
+- [Testing Reference](./testing.md) — Test suite documentation
 - [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos
 - [Technical Reference](./technical.md) — Source code documentation
 - [Architecture](../../explanation/documentation/aggregation-architecture.md) — System design

docs/reference/documentation/technical.md

@@ -173,6 +173,8 @@ Key architectural decisions are documented in the source repository:
 
 ## See Also
 
+- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
 - [Testing Reference](./testing.md) — Test suite documentation
+- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos
 - [Configuration Reference](./configuration.md) — Complete configuration field reference
 - [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — How the system works

docs/reference/documentation/testing.md

@@ -224,6 +224,7 @@ Integration tests may fail if:
 
 ## See Also
 
+- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
 - [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation
 - [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation
 - [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options

docs/tutorials/documentation.md

@@ -0,0 +1,28 @@
+---
+title: "Contributing to the Garden Linux Documentation"
+description: "Learn how to contribute to Garden Linux documentation — quick edits"
+---
+
+# Contributing to the Garden Linux Documentation
+
+Garden Linux documentation is published at **https://gardenlinux-docs.netlify.app/** and combines content from multiple repositories into a unified documentation site.
+
+> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
+
+## Quick Edits — The Easy Way
+
+The easiest way to improve the documentation is directly from the published site:
+
+1. **Navigate to any page** on https://gardenlinux-docs.netlify.app/
+2. **Scroll to the bottom** of the page
+3. **Click "Edit this page on GitHub"** — this opens the source file in the correct repository
+4. **Make your edits** using GitHub's web editor
+5. **Submit a pull request** — the changes will be automatically aggregated into the documentation site
+
+## See Also
+
+- [Working with the Documentation System Locally](../how-to/documentation/working-locally.md)
+- [Testing Reference](../reference/documentation/testing.md) — Test suite documentation
+- [Adding Repositories](../how-to/documentation/adding-repos.md) — How to add new repos
+- [Technical Reference](../reference/documentation/technical.md) — Source code documentation
+- [Architecture](../explanation/documentation/aggregation-architecture.md) — System design