docs: complete documentation refactor

google-labs-jules[bot] · google-labs-jules[bot] · commit 1dbbb6054edc · 2025-09-06T20:10:03.000Z
This commit finalizes the comprehensive refactoring of the /docs directory.

- Implements a dual-TOC structure with a master `docs/README.md` and scoped `docs/&lt;namespace&gt;.md` files.
- Reorders the namespaces in the master TOC to a more logical, user-centric flow.
- Adds a clickable breadcrumb navigation trail to the top of every documentation file.
- Establishes an `in-dev` namespace for work-in-progress documents, which are excluded from the TOCs.
- Updates `AGENTS.md` with all new documentation rules and conventions.
diff --git a/AGENTS.md b/AGENTS.md
@@ -88,14 +88,21 @@ repository:
   to the core principles, especially being code-independent.
 - **Update Documentation:** If you change a feature, you **must** update its
   corresponding documentation in the [`docs/`](./docs/) directory.
-  If you add a new feature, you **must** create a new documentation file for
-  it, following the namespace and dual-TOC structure. This means:
-  1.  Identify the correct namespace for your documentation (e.g., `development`, `workflows`).
-  2.  Create a new file named `docs/<namespace>.<your-topic>.md`.
-  3.  Add a link to your new file in **two** places:
-      - The main Table of Contents in `docs/README.md`, under the appropriate namespace heading.
+  All documentation must follow these rules:
+  1.  **Breadcrumb:** The first line of every documentation file must be a
+      clickable breadcrumb trail with correct relative links.
+      - For `docs/README.md`: `[base](../README.md) > docs`
+      - For `docs/ai.md`: `[base](../README.md) > [docs](./README.md) > ai`
+      - For `docs/ai.prompting.md`: `[base](../../README.md) > [docs](../README.md) > [ai](./ai.md) > Prompting AI Agents`
+  2.  **`in-dev` Namespace:** Any documentation that is a work-in-progress or
+      not ready for general use should be placed in the `in-dev` namespace
+      (e.g., `docs/in-dev.my-draft.md`). Files in this namespace are
+      automatically excluded from all Tables of Contents.
+  3.  **Dual TOC Structure:** If you add a new, non-`in-dev` documentation file,
+      you **must** add a link to it in **two** places:
+      - The main Table of Contents in `docs/README.md`, under the appropriate
+        namespace heading.
       - The namespace-specific index file, `docs/<namespace>.md`.
-  4.  If you are creating a new namespace, you must also create a `docs/<namespace>.md` index file and link to it from the main `docs/README.md`.
 - **Verify Your Work:** After creating or modifying a file, use a read-only
   tool like `read_file` or `ls` to confirm your changes were applied
   correctly before marking a step as complete.
diff --git a/docs/README.md b/docs/README.md
@@ -1,10 +1,8 @@
-# Documentation
-
-This directory contains the documentation for the `base` project.
+[base](../README.md) > docs
 
-- [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template.
+# Documentation
 
-[Guides](#guides) - [Development](#development) - [CI/CD](#cicd-workflows) - [Publishing](#publishing-your-project) - [Updating](#updating) - [Project Management](#project-management) - [Community](#community) - [AI](#ai) - [Documentation](#documentation-best-practices)
+[Guides](#guides) - [Development](#development) - [CI/CD Workflows](#cicd-workflows) - [Publishing](#publishing) - [Updating](#updating) - [Project Management](#project-management) - [Community](#community) - [AI](#ai) - [Documentation Best Practices](#documentation-best-practices)
 
 ## Guides
 
@@ -27,12 +25,12 @@ This directory contains the documentation for the `base` project.
 - [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions.
 - [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron.
 
-## Publishing Your Project
+## Publishing
 
-- **[Publishing with Markdown](./publishing.markdown.md)** - This is the simplest way to get started.
-- **[Advanced Publishing with HTML](./publishing.html.md)** - For those who need more control over their site's layout and appearance.
-- **[Publishing with Magic Links](./publishing.magic-links.md)** - This guide explains a powerful feature for community-driven sites.
-- **[GitHub Pages](./publishing.github-pages.md)** - This document provides more detail on how the underlying GitHub Pages service works.
+- [Publishing with Markdown](./publishing.markdown.md) - The simplest way to get started with publishing content.
+- [Advanced Publishing with HTML](./publishing.html.md) - For those who need more control over their site's layout and appearance.
+- [Publishing with Magic Links](./publishing.magic-links.md) - A powerful feature for community-driven sites.
+- [GitHub Pages](./publishing.github-pages.md) - More detail on how the underlying GitHub Pages service works.
 
 ## Updating
 
diff --git a/docs/ai.agents-md.md b/docs/ai.agents-md.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [ai](./ai.md) > Guiding AI with AGENTS.md
+
 # Guiding AI with `AGENTS.md`
 
 The `AGENTS.md` file is a special document within this repository designed to
diff --git a/docs/ai.md b/docs/ai.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > ai
+
 # AI
 
 This section contains documentation related to Artificial Intelligence.
diff --git a/docs/ai.prompting.md b/docs/ai.prompting.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [ai](./ai.md) > Prompting AI Agents
+
 # Prompting AI Agents for `attogram/base` Projects
 
 When using AI agents to create or update a repository based on
diff --git a/docs/base.md b/docs/base.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > base
+
 # The `base` Philosophy
 
 Welcome to `base`.
diff --git a/docs/community.building.md b/docs/community.building.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [community](./community.md) > Community Building Guide
+
 # Community Building Guide
 
 A thriving open-source project is built on a foundation of a healthy,
diff --git a/docs/community.discussions.md b/docs/community.discussions.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [community](./community.md) > Using GitHub Discussions
+
 # Using GitHub Discussions
 
 GitHub Discussions is a feature designed to be the community forum for your
diff --git a/docs/community.issue-management.md b/docs/community.issue-management.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [community](./community.md) > Issue Management Guide
+
 # Issue Management Guide
 
 Effective issue management is key to keeping your project organized and your
diff --git a/docs/community.md b/docs/community.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > community
+
 # Community
 
 This section contains documentation related to community management.
diff --git a/docs/community.wiki.md b/docs/community.wiki.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [community](./community.md) > Using the GitHub Wiki
+
 # Using the GitHub Wiki
 
 The GitHub Wiki is a powerful tool for hosting detailed, long-form documentation
diff --git a/docs/deployment.md b/docs/deployment.md
diff --git a/docs/development.codespaces.md b/docs/development.codespaces.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [development](./development.md) > GitHub Codespaces
+
 # GitHub Codespaces
 
 This repository is configured to use
diff --git a/docs/development.docker.md b/docs/development.docker.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [development](./development.md) > Docker Environment
+
 # Docker-based Development Environment
 
 This repository includes a Docker-based development environment to ensure a
diff --git a/docs/development.md b/docs/development.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > development
+
 # Development
 
 This section contains documentation related to development practices and environment setup.
diff --git a/docs/development.package-json.md b/docs/development.package-json.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [development](./development.md) > package.json Guide
+
 # `package.json` and `package-lock.json`
 
 You may notice `package.json` and `package-lock.json` files in the root of
diff --git a/docs/development.prettier.md b/docs/development.prettier.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [development](./development.md) > Using Prettier
+
 # Prettier for Code Formatting
 
 [Prettier](https://prettier.io/) is an opinionated code formatter that enforces a consistent code style across the entire project. This repository is configured to use Prettier in two ways: automatically via a GitHub workflow and manually for local development.
diff --git a/docs/documentation.best-practices.md b/docs/documentation.best-practices.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [documentation](./documentation.md) > Documentation Best Practices
+
 # Documentation Best Practices
 
 Good documentation is one of the most important aspects of a successful
diff --git a/docs/documentation.md b/docs/documentation.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > documentation
+
 # Documentation
 
 This section contains documentation about writing documentation.
diff --git a/docs/guides.md b/docs/guides.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > guides
+
 # Guides
 
 This section contains guides for using this project.
diff --git a/docs/guides.software-project.md b/docs/guides.software-project.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [guides](./guides.md) > Software Project Guide
+
 # Use Case: A Starting Point for Your Software Project
 
 This repository is designed to be a robust foundation for a wide variety of
diff --git a/docs/in-dev.render.md b/docs/in-dev.render.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > in-dev > Render Deployment
+
 # Deploying to Render.com
 
 > [!WARNING]
diff --git a/docs/project.badges.md b/docs/project.badges.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [project](./project.md) > Repository Badges
+
 # Badges
 
 Badges are a common way to display the status of your project in your
diff --git a/docs/project.launch-checklist.md b/docs/project.launch-checklist.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [project](./project.md) > Launch Checklist
+
 # Project Launch Checklist
 
 Launching a new open-source project can be a daunting task.
diff --git a/docs/project.licensing.md b/docs/project.licensing.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [project](./project.md) > Licensing Info
+
 # Licensing Information
 
 This repository is distributed under the MIT License, the full text of which
diff --git a/docs/project.md b/docs/project.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > project
+
 # Project Management
 
 This section contains documentation related to project management.
diff --git a/docs/project.security.md b/docs/project.security.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [project](./project.md) > Security Best Practices
+
 # Security Best Practices for Maintainers
 
 As an open-source maintainer, you have a responsibility to ensure your
diff --git a/docs/project.standard-files.md b/docs/project.standard-files.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [project](./project.md) > Standard Files
+
 # Standard Repository Files
 
 This document explains the purpose of the standard, language-agnostic
diff --git a/docs/project.template-repo.md b/docs/project.template-repo.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [project](./project.md) > Template Repo Guide
+
 # Maintaining `base` as a Template Repository
 
 This document is for maintainers of the `base` repository.
diff --git a/docs/project.versioning.md b/docs/project.versioning.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [project](./project.md) > Versioning Guide
+
 # Versioning and Release Management
 
 A well-defined versioning and release strategy is crucial for any professional
diff --git a/docs/publishing.github-pages.md b/docs/publishing.github-pages.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > GitHub Pages
+
 # GitHub Pages Site
 
 This repository is configured to use [GitHub Pages](https://pages.github.com/)
diff --git a/docs/publishing.html.md b/docs/publishing.html.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > Advanced Publishing with HTML
+
 # Advanced Publishing: HTML, Previews, and More
 
 This guide covers the more advanced features of the publishing platform,
diff --git a/docs/publishing.magic-links.md b/docs/publishing.magic-links.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > Publishing with Magic Links
+
 # Publishing with Magic Links
 
 "Magic Links" are special URLs that can pre-fill a new file in a GitHub
diff --git a/docs/publishing.markdown.md b/docs/publishing.markdown.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > Publishing with Markdown
+
 # Publishing with Markdown
 
 This repository is pre-configured to act as a simple, powerful, and free
diff --git a/docs/publishing.md b/docs/publishing.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > publishing
+
 # Publishing Your Project
 
 This repository is pre-configured to act as a simple, powerful, and free
diff --git a/docs/updating.adding-base-to-existing-repo.md b/docs/updating.adding-base-to-existing-repo.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [updating](./updating.md) > Adding base to an Existing Repo
+
 # Merging `base` Into an Existing Repository
 
 This guide explains how to merge the `attogram/base` repository into your
diff --git a/docs/updating.md b/docs/updating.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > updating
+
 # Updating
 
 This section contains documentation about updating the repository.
diff --git a/docs/updating.syncing-your-repo-when-base-is-updated.md b/docs/updating.syncing-your-repo-when-base-is-updated.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [updating](./updating.md) > Syncing Your Repo When base is Updated
+
 # Syncing Your Repo When `base` is Updated
 
 This guide explains how to sync your repository with the latest changes from the
diff --git a/docs/workflows.ci.md b/docs/workflows.ci.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > CI Workflow
+
 # CI Workflow
 
 The CI (Continuous Integration) workflow is defined in `.github/workflows/ci.yml`.
diff --git a/docs/workflows.md b/docs/workflows.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > workflows
+
 # CI/CD Workflows
 
 This repository includes several GitHub Actions workflows to automate various tasks. Each workflow is defined in a `.yml` file in the `.github/workflows` directory.
diff --git a/docs/workflows.pages.md b/docs/workflows.pages.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > GitHub Pages Deployment
+
 # GitHub Pages Deployment Workflow
 
 The GitHub Pages deployment workflow is defined in `.github/workflows/pages.yml`. Its purpose is to build and deploy the repository's content as a GitHub Pages website.
diff --git a/docs/workflows.prettier.md b/docs/workflows.prettier.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Prettier Workflow
+
 # Prettier Workflow
 
 The Prettier workflow, defined in `.github/workflows/prettier.yml`, automates code formatting for the entire repository.
diff --git a/docs/workflows.release-on-tag.md b/docs/workflows.release-on-tag.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Release on Tag
+
 # Release on Tag Workflow
 
 The "Create Release" workflow, defined in `.github/workflows/release-on-tag.yml`, automates the process of creating a new GitHub release whenever a new tag is pushed to the repository.
diff --git a/docs/workflows.scheduling.md b/docs/workflows.scheduling.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Workflow Scheduling
+
 # Scheduling Workflows with Cron
 
 GitHub Actions allows you to automate tasks on a schedule, similar to the
diff --git a/docs/workflows.secrets-management.md b/docs/workflows.secrets-management.md
@@ -1,3 +1,5 @@
+[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Secrets Management
+
 # Secrets Management in GitHub Actions
 
 Properly managing secrets like API keys, access tokens, and other credentials
