Merge pull request #38 from attogram/docs/consolidate-workflows

Reorder documentation namespaces for better logical flow

Author: attogram

AGENTS.md

@@ -49,9 +49,10 @@ repository:
   - [`SECURITY.md`](./.github/SECURITY.md): A template for the user's
     security policy.
 
-- **[`docs/`](./docs/)**: Contains all documentation for the project.
-  Each major feature or component has its own corresponding `.md` file in this
-  directory.
+- **[`docs/`](./docs/)**: Contains all documentation for the project. The documentation is organized into namespaces.
+  - **`docs/README.md`**: The main entry point for documentation, which serves as a Table of Contents.
+  - **`docs/<namespace>.md`**: Each namespace has a top-level index file (e.g., `docs/ai.md`) that provides an overview and links to all the sub-pages within that namespace.
+  - **`docs/<namespace>.<topic>.md`**: Individual documentation pages for specific topics within a namespace.
 
 - **[`docker/`](./docker/)**: Contains the development environment.
   - [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX
@@ -88,7 +89,13 @@ repository:
 - **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.
+  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.
+      - 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.

docs/README.md

@@ -3,24 +3,12 @@
 This directory contains the documentation for the `base` project.
 
 - [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template.
-- [Documentation Index](./README.md) - You are here.
 
-## AI
-
-- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents.
-- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents.
+[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)
 
-## CI/CD
-
-- [Secrets Management](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions.
-- [Workflow Scheduling](./workflows.scheduling.md) - Automating recurring tasks with cron.
-- [GitHub Workflows](./workflows.md) - Explanation of the CI/CD workflows.
-
-## Community
+## Guides
 
-- [Community Building Guide](./community.building.md) - Fostering a healthy and effective community.
-- [Using GitHub Discussions](./community.discussions.md) - Leveraging Discussions for community conversations.
-- [Issue Management Guide](./community.issue-management.md) - Best practices for triaging issues.
+- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project.
 
 ## Development
 
@@ -30,13 +18,21 @@ This directory contains the documentation for the `base` project.
 - [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier.
 - [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code.
 
-## Documentation
+## CI/CD Workflows
 
-- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation.
+- [**CI Workflow**](./workflows.ci.md) (`ci.yml`) - Ensures code quality by running linting checks on every push and pull request to the `main` branch.
+- [**GitHub Pages Deployment**](./workflows.pages.md) (`pages.yml`) - Builds and deploys the repository's content as a GitHub Pages website.
+- [**Prettier Workflow**](./workflows.prettier.md) (`prettier.yml`) - Automatically formats the code in the repository using Prettier and commits the changes.
+- [**Release on Tag**](./workflows.release-on-tag.md) (`release-on-tag.yml`) - Automates the creation of GitHub Releases when a new version tag is pushed.
+- [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions.
+- [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron.
 
-## Guides
+## Publishing Your Project
 
-- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project.
+- **[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.
 
 ## Updating
 
@@ -53,10 +49,17 @@ This directory contains the documentation for the `base` project.
 - [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template.
 - [Versioning Guide](./project.versioning.md) - Professional release management.
 
-## Publishing
+## Community
 
-- [Publishing Overview](./publishing.md) - An overview of the different ways to publish content.
-- [Publishing with Markdown](./publishing.markdown.md) - The simplest way to create pages.
-- [Advanced Publishing with HTML](./publishing.html.md) - For more control over layout and style.
-- [Publishing with Magic Links](./publishing.magic-links.md) - Creating links that pre-fill new file content.
-- [GitHub Pages](./publishing.github-pages.md) - How the underlying publishing system works.
+- [Community Building Guide](./community.building.md) - Fostering a healthy and effective community.
+- [Using GitHub Discussions](./community.discussions.md) - Leveraging Discussions for community conversations.
+- [Issue Management Guide](./community.issue-management.md) - Best practices for triaging issues.
+
+## AI
+
+- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents.
+- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents.
+
+## Documentation Best Practices
+
+- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation.

docs/ai.md

@@ -0,0 +1,6 @@
+# AI
+
+This section contains documentation related to Artificial Intelligence.
+
+- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents.
+- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents.

docs/community.md

@@ -0,0 +1,7 @@
+# Community
+
+This section contains documentation related to community management.
+
+- [Community Building Guide](./community.building.md) - Fostering a healthy and effective community.
+- [Using GitHub Discussions](./community.discussions.md) - Leveraging Discussions for community conversations.
+- [Issue Management Guide](./community.issue-management.md) - Best practices for triaging issues.

docs/deployment.md

@@ -0,0 +1,5 @@
+# Deployment
+
+This section contains documentation related to deployment.
+
+- [Render Deployment](./deployment.render.md) - How to deploy the application to Render.

docs/development.md

@@ -0,0 +1,9 @@
+# Development
+
+This section contains documentation related to development practices and environment setup.
+
+- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development.
+- [Docker Environment](./development.docker.md) - Using the included Docker setup.
+- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files.
+- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier.
+- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code.

docs/documentation.md

@@ -0,0 +1,5 @@
+# Documentation
+
+This section contains documentation about writing documentation.
+
+- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation.

docs/guides.md

@@ -0,0 +1,5 @@
+# Guides
+
+This section contains guides for using this project.
+
+- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project.

docs/project.md

@@ -0,0 +1,11 @@
+# Project Management
+
+This section contains documentation related to project management.
+
+- [Repository Badges](./project.badges.md) - How to use and create repository badges.
+- [Launch Checklist](./project.launch-checklist.md) - A reusable checklist for project launches.
+- [Licensing Info](./project.licensing.md) - Details on the MIT License.
+- [Security Best Practices](./project.security.md) - Basic security practices for maintainers.
+- [Standard Files](./project.standard-files.md) - Explanation of standard repo files.
+- [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template.
+- [Versioning Guide](./project.versioning.md) - Professional release management.

docs/updating.md

@@ -0,0 +1,6 @@
+# Updating
+
+This section contains documentation about updating the repository.
+
+- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template.
+- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it.