Added linter and AI review to stack docs with intentional mistakes

docs/index.md

@@ -1,5 +1,68 @@
-# Hello, world!
+# Dave's Documentation Publishing Machine
 
-This is an index file for my docs as code thing.
+This project allows me to learn continuous integration and continuous deployment practices for documentation.
 
-I **love** docs as code!
+I **love** docs as code! I'm really enjoying the multidisciplinary nature of setting up and operating the pipeline:
+
+* writing markdown
+* operating stuff from the terminal
+* working with git
+* setting up stuff in GitHub
+* writing workflows in YAML
+* vibe coding node modules
+* developing AI prompts
+* operating APIs
+
+I feel like a real hacker! :)
+
+## The Pipeline
+
+Here's how the whole thing works.
+
+### First-time setup
+
+Prerequisites: a local clone of the repository, Git, Python with pip, and Node.js 22 or newer.
+
+Run all commands from the repository root. The commands below use PowerShell.
+
+1. Install mkDocs: ```pip install mkdocs```
+1. Install the AI review dependency: ```npm ci --prefix .github/ai-review```
+1. Create an _.env_ file in the repository root with your own API key and model:
+
+   ```dotenv
+   OPENAI_API_KEY=your-api-key
+   OPENAI_MODEL=your-model-id
+   ```
+
+### Contributing
+
+Follow these steps when you want to contribute to the docs.
+
+1. Pull _master_.
+1. Create a new local branch.
+1. Write.
+1. Stage the changes (don't commit).
+1. Run the AI preview: ```node --env-file=.env .\.github\ai-review\review.mjs --preview```
+1. Run ```mkdocs serve``` to check how your work looks on the generated site. Open <http://127.0.0.1:8000/> in your browser.
+1. Commit.
+1. Create a PR for merging your branch to _master_.
+
+### Automatic PR checks
+
+A GitHub Actions workflow runs when a PR is created or when you push the PR branch. The workflow is defined in _.github\workflows\pr-checks.yml_.
+
+The AI review is skipped for PRs from forks.
+
+This happens automatically:
+
+1. Run MarkdownLint to validate the markdown. Only the _docs_ folder is validated. The workflow stops if it finds errors.
+1. Run ```mkdocs build --strict``` to check that the site builds. If the build fails, the workflow stops.
+1. Generate a diff of your changes against master.
+1. Run the AI review (_.github\ai-review\review.mjs_) on the diff.
+1. Post the AI review as a PR comment. Token consumption information appears in the GitHub Actions job summary. The AI review is advisory, findings do not block merging the PR.
+
+After I review the PR, I merge it manually.
+
+### Publishing
+
+A GitHub Actions workflow builds and publishes the site in GitHub Pages when changes to _docs/_ or _mkdocs.yml_ are pushed to _master_, including when a PR is merged. You can also run it manually from the Actions tab. The workflow is defined in _.github\workflows\builddocs.yml_.

docs/stack.md

@@ -1,33 +1,61 @@
 # My Docs as Code stack
 
-I'm using these tools in the pipeline.
+This page details the tools used in the pipeline and my reasoning for choosing those tools. For details about the pipeline itself, see [the home page](index.md).
 
 ## Authoring
 
-I write markdown files with **Notepad++**.
+I write markdown and the associated infrastructure code with **Notepad++**. It's the simplest tool that I already had on my computer. It is sufficient for this small prototype.
 
-I use the following plugins:
+I use [AnotherMarkdown](https://github.com/ezyuzin/NppAnotherMarkdown) to preview the rendered markdown.
 
-- [AnotherMarkdown](https://github.com/ezyuzin/NppAnotherMarkdown)
+Future consideration: I will switch to VS Code for production projects as it provides a more integrated coding experience.
 
-## Versioning
+## Source control
 
-I use Git on Windows locally. I host the repository on GitHub.
+Locally, I use **Git for Windows**. The [remote repository](https://github.com/davidstula/docsmachine) lives on **GitHub**.
 
-[Open the repository](https://github.com/davidstula/docsmachine)
+I use **GitHub CLI** from a **PowerShell** terminal. I'm authenticated via a GitHub token (the classic type) and communicate through HTTPS.
 
-To operate GitHub I use GitHub CLI in a PowerShell terminal. I'm authenticated via a Github token (the classic type) and communicating through HTTPS.
+GitHub is the most obvious choice for learning continuous integration practices and tools, as it's widely used and has detailed documentation.
 
-## Static site generator
+## Creating outputs
 
-I use [mkDocs](https://www.mkdocs.org/) to generate and serve a local version of the docs site.
+I use **[mkDocs](https://www.mkdocs.org/)** to generate a static site.
 
-## Automation
+Locally, I use the mkDocs _serve_ function to preview the end result. On GitHub, I use mkDocs to generate the site in a GitHub Actions workflow.
 
-A GitHub Action workflow executes on a pull request to the "master" branch. The workflow runs on an Ubuntu runner with Python and does the following:
+mkDocs uses its default settings.
 
-1. Install mkDocs.
-1. Check out the master branch.
-1. Run ```mkdocs build```.
-1. Upload the resulting ```site``` folder to Github Pages as an artifact.
-1. Deploy the pages.
+I chose mkDocs randomly. I didn't want to spend time evaluating static side generators so I just picked the first one I found.
+
+Future consideration: For simple pipelines such as this, I would use Jekyll, which is already integrated in GitHub.
+
+## Publishing
+
+I use **GitHub Pages** to publish the generated site.
+
+A **GitHub Actions** workflow uses mkDocs to generate the output and publish it when changes to _docs/_ or _mkdocs.yml_ are pushed to _master_, including when a PR is merged. The workflow can also be run manually from the Actions tab.
+
+## Content review
+
+The documentation content goes through automated review. The following happens when a new pull request is created:
+
+1. **MarkdownLint** validates the markdown code.
+1. **mkDocs** checks that the site builds with the _--strict_ option.
+1. OpenAI's **GPT-5.6 Luna** LLM reviews the content for clarity.
+
+The AI review runs only if the markdown validation and build pass. It is skipped for PRs from forks.
+
+I chose MarkdownLint as it's available as a published GitHub action, is widely used, and has high ratings.
+
+I chose GPT-5.6 Luna as the model that does the review because it's cheap and provides decent quality of responses.
+
+### Local AI review
+
+The same Node.js module can be used locally with the ```--preview``` argument to generate an AI review of staged changes without having to commit the changes.
+
+### AI review stack
+
+A **Node.js** module orchestrates the AI review. It calls **OpenAI's JavaScript SDK** and uses GitHub CLI to post the review as a comment to the pull request.
+
+These are tools I was somewhat familiar with so they represent the obvious choice for learning.