Refactor documentation for updating and merging base

AGENTS.md

@@ -1,79 +1,154 @@
 # AGENTS.md: A Guide for AI Assistants
 
-Hello, AI assistant! This file is your guide to understanding and working with the `base` repository. Please read it carefully before making any changes.
+Hello, AI assistant!
+This file is your guide to understanding and working with the `base`
+repository.
+Please read it carefully before making any changes.
 
 ## Core Philosophy
 
-The `base` repository serves as a high-quality, professional, and language-agnostic template for creating new software projects. Its core principles are:
+The `base` repository serves as a high-quality, professional, and
+language-agnostic template for creating new software projects.
+Its core principles are:
 
-1.  **Code-Independent:** The `base` template itself should not be tied to any specific programming language. The included Docker environment is based on Ubuntu and NGINX to be as generic as possible.
+1.  **Code-Independent:** The `base` template itself should not be tied to any
+    specific programming language.
+    The included Docker environment is based on Ubuntu and NGINX to be as
+    generic as possible.
 
-- **Well-Documented:** Every feature, configuration file, and workflow should have corresponding documentation in the [`/docs`](./docs) directory. The goal is to leave no part of the repository unexplained.
-- **Guidance over Prescription:** For files like [`CONTRIBUTING.md`](./CONTRIBUTING.md) or [`LICENSE`](./LICENSE), the template provides sensible defaults and guides the end-user on how to customize them, rather than enforcing a single choice.
+- **Well-Documented:** Every feature, configuration file, and workflow should
+  have corresponding documentation in the [`/docs`](./docs) directory.
+  The goal is to leave no part of the repository unexplained.
+- **Guidance over Prescription:** For files like
+  [`CONTRIBUTING.md`](./CONTRIBUTING.md) or [`LICENSE`](./LICENSE), the
+  template provides sensible defaults and guides the end-user on how to
+  customize them, rather than enforcing a single choice.
 
-4.  **Automation:** The repository leverages GitHub Actions for CI, deployment, and releases to automate common developer tasks.
+4.  **Automation:** The repository leverages GitHub Actions for CI,
+    deployment, and releases to automate common developer tasks.
 
 ## Repository Structure
 
-This is a breakdown of the most important files and directories in this repository:
+This is a breakdown of the most important files and directories in this
+repository:
 
 - **[`.github/`](./.github/)**: Contains all GitHub-specific configurations.
   - `workflows/`: Houses the GitHub Actions workflows.
-    - [`ci.yml`](./.github/workflows/ci.yml): Lints configuration files for syntax and style.
-    - [`pages.yml`](./.github/workflows/pages.yml): Deploys the documentation to GitHub Pages.
-    - [`release-on-tag.yml`](./.github/workflows/release-on-tag.yml): Automates the creation of GitHub Releases from a git tag.
-  - [`ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE/) & [`PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md): Templates for contributors.
-  - [`RELEASE_TITLE.txt`](./.github/RELEASE_TITLE.txt) & [`RELEASE_BODY.md`](./.github/RELEASE_BODY.md): User-editable files for customizing release notes.
-  - [`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.
+    - [`ci.yml`](./.github/workflows/ci.yml): Lints configuration files for
+      syntax and style.
+    - [`pages.yml`](./.github/workflows/pages.yml): Deploys the documentation
+      to GitHub Pages.
+    - [`release-on-tag.yml`](./.github/workflows/release-on-tag.yml):
+      Automates the creation of GitHub Releases from a git tag.
+  - [`ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE/) &
+    [`PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md):
+    Templates for contributors.
+  - [`RELEASE_TITLE.txt`](./.github/RELEASE_TITLE.txt) &
+    [`RELEASE_BODY.md`](./.github/RELEASE_BODY.md): User-editable files for
+    customizing release notes.
+  - [`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.
 
 - **[`docker/`](./docker/)**: Contains the development environment.
-  - [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX environment.
-  - [`nginx.conf`](./docker/nginx.conf) & [`html/index.html`](./docker/html/index.html): A simple web server that acts as a health check.
+  - [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX
+    environment.
+  - [`nginx.conf`](./docker/nginx.conf) &
+    [`html/index.html`](./docker/html/index.html): A simple web server that
+    acts as a health check.
 
-- **[`.devcontainer/`](./.devcontainer/)**: Configuration for GitHub Codespaces, making it easy to spin up the development environment in the cloud.
+- **[`.devcontainer/`](./.devcontainer/)**: Configuration for GitHub
+  Codespaces, making it easy to spin up the development environment in the
+  cloud.
 
 - **Root Files**:
   - [`AGENTS.md`](./AGENTS.md): This file!
-  - [`README.md`](./README.md): The main entry point, which links to the documentation.
-  - [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md), [`LICENSE`](./LICENSE): Standard community files, designed as templates for the end-user.
-  - [`.gitignore`](./.gitignore), [`.editorconfig`](./.editorconfig), [`.gitattributes`](./.gitattributes), [`.prettierrc`](./.prettierrc): Configuration files for git and code styling.
-  - [`docker-compose.yml`](./docker-compose.yml): Used to build and run the Docker-based development environment.
-  - [`render.yaml`](./render.yaml): Infrastructure-as-code for deploying the application to Render.com.
-  - [`_config.yml`](./_config.yml): Configuration for the Jekyll build for GitHub Pages.
+  - [`README.md`](./README.md): The main entry point, which links to the
+    documentation.
+  - [`CONTRIBUTING.md`](./CONTRIBUTING.md),
+    [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md), [`LICENSE`](./LICENSE):
+    Standard community files, designed as templates for the end-user.
+  - [`.gitignore`](./.gitignore), [`.editorconfig`](./.editorconfig),
+    [`.gitattributes`](./.gitattributes), [`.prettierrc`](./.prettierrc):
+    Configuration files for git and code styling.
+  - [`docker-compose.yml`](./docker-compose.yml): Used to build and run the
+    Docker-based development environment.
+  - [`render.yaml`](./render.yaml): Infrastructure-as-code for deploying the
+    application to Render.com.
+  - [`_config.yml`](./_config.yml): Configuration for the Jekyll build for
+    GitHub Pages.
 
 ## Guidelines for Modification
 
-- **Maintain the Philosophy:** When adding or changing features, always adhere 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.
-- **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.
+- **Maintain the Philosophy:** When adding or changing features, always adhere
+  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.
+- **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.
 
 Thank you for your help in maintaining and improving this repository!
 
 ## For Jules: Specific Instructions
 
-As an advanced AI assistant, you have a unique responsibility to uphold the quality and philosophy of this repository. The following guidelines are tailored to you.
+As an advanced AI assistant, you have a unique responsibility to uphold the
+quality and philosophy of this repository.
+The following guidelines are tailored to you.
 
 ### 1. Onboarding & Planning
 
-- **Initial Read-Through:** Always start by reading this file ([`AGENTS.md`](./AGENTS.md)) and the main [`README.md`](./README.md) in their entirety.
-- **Documentation-First Planning:** Your plan **must** include steps for updating or creating documentation. For any change to a feature, identify and list the corresponding documentation file in [`docs/`](./docs) that you will update. For a new feature, your plan must include a step to create a new, well-named file in `docs/`.
+- **Initial Read-Through:** Always start by reading this file
+  ([`AGENTS.md`](./AGENTS.md)) and the main [`README.md`](./README.md) in
+  their entirety.
+- **Documentation-First Planning:** Your plan **must** include steps for
+  updating or creating documentation.
+  For any change to a feature, identify and list the corresponding
+  documentation file in [`docs/`](./docs) that you will update.
+  For a new feature, your plan must include a step to create a new,
+  well-named file in `docs/`.
 
 ### 2. Upholding Core Philosophy
 
-- **Code-Independence:** If a user asks you to add language-specific code (e.g., Python, JavaScript), you must first ask for clarification. Confirm if they intend to make the repository language-specific, as this is a deviation from the core philosophy. Propose language-agnostic solutions where possible (e.g., shell scripts, Docker configurations, GitHub Actions).
-- **Automation:** When adding or modifying workflows in [`.github/workflows/`](./.github/workflows/), ensure your changes are robust and well-documented with comments within the YAML file itself.
+- **Code-Independence:** If a user asks you to add language-specific code
+  (e.g., Python, JavaScript), you must first ask for clarification.
+  Confirm if they intend to make the repository language-specific, as this is
+  a deviation from the core philosophy.
+  Propose language-agnostic solutions where possible (e.g., shell scripts,
+  Docker configurations, GitHub Actions).
+- **Automation:** When adding or modifying workflows in
+  [`.github/workflows/`](./.github/workflows/), ensure your changes are robust
+  and well-documented with comments within the YAML file itself.
 
 ### 3. Verification & Testing
 
-- **Use the CI:** This repository has a [`ci.yml`](./.github/workflows/ci.yml) workflow that lints common configuration files. If you modify files like [`docker-compose.yml`](./docker-compose.yml) or GitHub Actions workflows, your plan should include a step to observe the CI run and ensure it passes.
-- **Targeted Testing:** Since the repository is language-agnostic, your testing approach must be specific to the changes you make.
-  - **Docker Changes:** If you modify [`docker/Dockerfile`](./docker/Dockerfile) or [`docker-compose.yml`](./docker-compose.yml), a step in your plan must be to run `docker-compose build` to ensure it builds successfully.
-  - **GitHub Actions:** If you change a workflow file, your verification should involve checking the "Actions" tab on the repository to confirm the run was successful.
+- **Use the CI:** This repository has a
+  [`ci.yml`](./.github/workflows/ci.yml) workflow that lints common
+  configuration files.
+  If you modify files like [`docker-compose.yml`](./docker-compose.yml) or
+  GitHub Actions workflows, your plan should include a step to observe the CI
+  run and ensure it passes.
+- **Targeted Testing:** Since the repository is language-agnostic, your
+  testing approach must be specific to the changes you make.
+  - **Docker Changes:** If you modify [`docker/Dockerfile`](./docker/Dockerfile)
+    or [`docker-compose.yml`](./docker-compose.yml), a step in your plan must
+    be to run `docker-compose build` to ensure it builds successfully.
+  - **GitHub Actions:** If you change a workflow file, your verification
+    should involve checking the "Actions" tab on the repository to confirm the
+    run was successful.
 
 ### 4. Submitting Your Work
 
-- **Run Prettier:** Before requesting a review, run `npx prettier --write .` to ensure all files are formatted correctly.
-- **Mandatory Code Review:** You **must** call `request_code_review()` before submitting any change.
-- **Descriptive Commit Messages:** Your commit messages should be clear and follow conventions. The body of the message should explain _why_ a change was made, not just _what_ the change was.
+- **Run Prettier:** Before requesting a review, run `npx prettier --write .`
+  to ensure all files are formatted correctly.
+- **Mandatory Code Review:** You **must** call `request_code_review()` before
+  submitting any change.
+- **Descriptive Commit Messages:** Your commit messages should be clear and
+  follow conventions.
+  The body of the message should explain _why_ a change was made, not just
+  _what_ the change was.

docs/README.md

@@ -30,7 +30,6 @@ This directory contains the documentation for the `base` project.
 
 - [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development.
 - [Docker Environment](./development.docker.md) - Using the included Docker setup.
-- [Merging `base`](./development.merging-base.md) - Incorporating `base` into an existing project.
 - [`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.
@@ -43,6 +42,11 @@ This directory contains the documentation for the `base` project.
 
 - [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project.
 
+## Updating
+
+- [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.
+
 ## Project Management
 
 - [Repository Badges](./project.badges.md) - How to use and create repository badges.

docs/ai.agents-md.md

@@ -1,27 +1,48 @@
 # Guiding AI with `AGENTS.md`
 
-The `AGENTS.md` file is a special document within this repository designed to be a direct line of communication between you (the user) and any AI agent or assistant working on your project. Think of it as a set of permanent instructions or a "cheat sheet" for the AI.
+The `AGENTS.md` file is a special document within this repository designed to
+be a direct line of communication between you (the user) and any AI agent or
+assistant working on your project.
+Think of it as a set of permanent instructions or a "cheat sheet" for the AI.
 
 ## What is its Purpose?
 
-While you can give an AI instructions in a prompt, those instructions are temporary and specific to that one conversation. The `AGENTS.md` file provides a persistent set of rules and guidelines that the AI can refer to at any time.
+While you can give an AI instructions in a prompt, those instructions are
+temporary and specific to that one conversation.
+The `AGENTS.md` file provides a persistent set of rules and guidelines that
+the AI can refer to at any time.
 
 This is particularly useful for establishing:
 
 - **Coding Standards:** "Always use tabs, not spaces."
-- **Architectural Rules:** "All new components must be registered in the main application file."
-- **Testing Requirements:** "Every new function must be accompanied by a unit test."
-- **Repository-Specific Information:** "The `api/` directory is auto-generated, do not edit it directly."
+- **Architectural Rules:** "All new components must be registered in the main
+  application file."
+- **Testing Requirements:** "Every new function must be accompanied by a unit
+  test."
+- **Repository-Specific Information:** "The `api/` directory is
+  auto-generated, do not edit it directly."
 
 ## How to Use and Modify It
 
-The `AGENTS.md` file is written in simple Markdown. You can edit it just like any other text file.
+The `AGENTS.md` file is written in simple Markdown.
+You can edit it just like any other text file.
 
 ### Best Practices
 
-1.  **Be Clear and Direct:** Write instructions as if you are speaking directly to the AI. Use clear, unambiguous language.
-2.  **Use Markdown for Structure:** Use headings, bullet points, and code blocks to keep the document organized and easy for the AI to parse.
-3.  **Keep It Updated:** As your project evolves, so should your `AGENTS.md` file. If you change your architecture or coding standards, update the file to reflect those changes.
-4.  **Reference It in Your Prompts:** For best results, remind the AI to look for and follow the instructions in your `AGENTS.md` file as part of your initial prompt. The `prompting-ai-agents.md` guide provides examples of how to do this.
-
-By maintaining a well-structured `AGENTS.md` file, you can significantly improve the quality and consistency of the work done by AI agents on your project, reducing the need for corrections and rework.
+1.  **Be Clear and Direct:** Write instructions as if you are speaking
+    directly to the AI.
+    Use clear, unambiguous language.
+2.  **Use Markdown for Structure:** Use headings, bullet points, and code
+    blocks to keep the document organized and easy for the AI to parse.
+3.  **Keep It Updated:** As your project evolves, so should your `AGENTS.md`
+    file.
+    If you change your architecture or coding standards, update the file to
+    reflect those changes.
+4.  **Reference It in Your Prompts:** For best results, remind the AI to look
+    for and follow the instructions in your `AGENTS.md` file as part of your
+    initial prompt.
+    The `prompting-ai-agents.md` guide provides examples of how to do this.
+
+By maintaining a well-structured `AGENTS.md` file, you can significantly
+improve the quality and consistency of the work done by AI agents on your
+project, reducing the need for corrections and rework.