doc: Add guides for prompting, AGENTS.md, and package.json

docs/README.md

@@ -7,6 +7,9 @@ This directory contains the documentation for the `base` project.
 - **[GitHub Codespaces](./github-codespaces.md)**: A guide to using GitHub Codespaces for a cloud-based development experience.
 - **[GitHub Pages Site](./github-pages.md)**: Information on how the project's documentation is automatically built and deployed as a website.
 - **[Use Case: A Publishing Platform](./use-case-publishing.md)**: A detailed guide on using this repository as a platform to create and publish your own website.
+- **[Prompting AI Agents](./prompting-ai-agents.md)**: A guide on how to effectively prompt AI agents when working on `base`-based projects.
+- **[Guiding AI with `AGENTS.md`](./agents-md-guide.md)**: An explanation of how to use the `AGENTS.md` file to provide persistent instructions to AI agents.
+- **[The `package.json` files](./package-json-guide.md)**: An explanation of the `package.json` and `package-lock.json` files used for development tooling.
 - **[GitHub Workflows](./github-workflows.md)**: An explanation of the CI/CD workflows for linting, testing, and releasing.
 - **[Licensing Information](./licensing.md)**: Details on the MIT License and how to properly attribute copyright.
 - **[Deploying to Render.com](./render.md)**: Instructions for deploying the project to the Render.com platform.

docs/agents-md-guide.md

@@ -0,0 +1,27 @@
+# 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.
+
+## 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.
+
+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."
+
+## 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.
+
+### 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.

docs/package-json-guide.md

@@ -0,0 +1,19 @@
+# `package.json` and `package-lock.json`
+
+You may notice `package.json` and `package-lock.json` files in the root of this repository. These files are part of the Node.js ecosystem and are used to manage project dependencies and scripts.
+
+## What is their Purpose in `base`?
+
+The `attogram/base` template is designed to be language-agnostic. However, it does use a few Node.js-based tools for development purposes to ensure code quality and consistency.
+
+- **`package.json`**: This file lists the development dependencies required to work on this repository. Primarily, this includes `prettier`, a code formatter that automatically ensures all configuration files and documentation adhere to a consistent style. It may also contain simple scripts that can be run with `npm run <script_name>`.
+
+- **`package-lock.json`**: This is an auto-generated file that records the exact version of every dependency used. This guarantees that every developer (and every AI agent) uses the exact same version of the tools, preventing inconsistencies and "it works on my machine" problems. **You should not edit this file manually.**
+
+## Do I Need Node.js?
+
+Strictly speaking, you only need Node.js and `npm` installed if you intend to run the development tools yourself, such as running `npx prettier --write .` to format files.
+
+The AI agents that work on this repository are expected to have these tools available and will use them to keep the codebase consistent. If you ask an AI agent to perform work, it will use these files to ensure its changes match the project's standards.
+
+If you are not a developer and are only using this repository to manage content, you can generally ignore these files. They are part of the "scaffolding" that keeps the project clean and maintainable.

docs/prompting-ai-agents.md

@@ -0,0 +1,51 @@
+# Prompting AI Agents for `attogram/base` Projects
+
+When using AI agents to create or update a repository based on `attogram/base`, providing a clear, upfront context is the most effective way to get the results you want. This guide provides two distinct prompt examples to help you steer AI agents in the right direction, whether you want to build upon the `base` philosophy or intentionally modify it.
+
+---
+
+## Prompt 1: Using `base` As-Is
+
+This prompt is ideal when you want to create a new project that adheres to the core, language-agnostic philosophy of the `attogram/base` template.
+
+### Example Prompt: Create a Personal Blog
+
+```
+This project builds upon the attogram/base template. Please integrate the new website content without removing the core base repository files or structure.
+
+The main homepage for the site is `README.md`, and all new content should be linked from there. You can create new directories for your content as needed, but please do not modify the core `base` files and directories (such as `.github`, `docs`, `docker`, etc.).
+
+Please use the existing Jekyll setup for the site, which builds from the root directory. Do not install other static site generators like Eleventy.
+
+Finally, please look for and follow any instructions in an `AGENTS.md` file, as it may contain project-specific guidelines for AI agents.
+```
+
+---
+
+## Prompt 2: Modifying `base` for a New Technology
+
+This prompt is for when you want to use `attogram/base` as a starting point but intend to introduce a specific programming language or framework. This example uses PHP and Laravel.
+
+### Example Prompt: Add a Laravel Backend
+
+```
+This project will use `attogram/base` as a foundation, but we will be modifying it to support a PHP/Laravel application.
+
+Here are the requirements:
+1.  **Add PHP and Laravel:** Please modify the Docker environment to include PHP and the necessary extensions for a Laravel application.
+2.  **Install Laravel:** Once the environment is updated, install a fresh copy of the Laravel framework in a `/src` directory at the repository root.
+3.  **Update NGINX:** Configure the NGINX server to point to the `public` directory of the Laravel application.
+4.  **Preserve Core Files:** Do not remove the existing GitHub Actions workflows or the documentation in the `/docs` directory. The goal is to integrate Laravel into the `base` template, not replace it.
+5.  **Check for `AGENTS.md`:** Please look for and follow any instructions in an `AGENTS.md` file, as it may contain project-specific guidelines for AI agents.
+```
+
+---
+
+## Why These Prompts Work
+
+Providing a detailed, upfront prompt like the examples above is crucial for several reasons:
+
+- **Sets Clear Expectations:** The AI immediately understands the scope of the project. It knows whether to preserve the `base` philosophy or to modify it, which is the most critical distinction.
+- **Reduces Errors and Rework:** By specifying the technology stack (or lack thereof) and the desired file structure, you prevent the AI from making incorrect assumptions that would need to be corrected later.
+- **Empowers the AI:** A clear prompt gives the AI the constraints it needs to be creative and effective. It can focus on the "how" because you've already defined the "what" and "why."
+- **Faster, Better Results:** Ultimately, a few minutes spent crafting a detailed prompt will save you hours of back-and-forth, leading to a better final product that meets your requirements from the start.