docs: Minor changes to README

- Improves notice of LLM-oriented docs
- Adds telemetry warning about Wave and Warp terminals
- Adds 'GUI' to glossary
- Adds 2 new ADR items
- Adds anchors for ADR description-list items
- Fixes minor style/grammar/linting issues

Author: briandominick

README.adoc

@@ -88,7 +88,8 @@ The provided system also works for solo practitioners who want a stable, isolate
 
 [TIP]
 ====
-LLMs or people engaging LLMs/agents to help them use DocOps Box should reference link:https://github.com/DocOps/box/blob/agent-docs/user-guidance/skill-skim.json[the Agent User Guidance skill].
+LLMs or people engaging LLMs/agents to help them use DocOps Box should reference link:https://raw.githubusercontent.com/DocOps/box/refs/heads/agent-docs/user-guidance/skill-skim.json[this JSON outline of the core agent guidance skill].
+There is also a link:https://raw.githubusercontent.com/DocOps/box/refs/heads/agent-docs/readme.md[Markdown version of this README] (with a link:https://raw.githubusercontent.com/DocOps/box/refs/heads/agent-docs/readme-skim.json[JSON skim outline] for token savings).
 ====
 
 Even if you don't use the images or tools provided, this guide should still be helpful for anyone orienting to the world of docs-as-code tools and workflows.
@@ -101,7 +102,7 @@ toc::[]
 == Introduction
 
 // tag::agent-guide[]
-This project is geared as a guide and assets for meeting *_non_-developer tech or clerical workers*, typically on their *Windows* or maybe *MacOS* systems, not yet set up as "`development environments`" with tools like [.buzz]*Ruby*, [.buzz]*Node.js*, [.buzz]*Python*, [.buzz]*Git*, [.buzz]*Pandoc*, [.buzz]*Vale* and the world of capabilities that these tools open up.
+This project provides a guide and assets for meeting *_non_-developer tech or clerical workers*, typically on their *Windows* or maybe *MacOS* systems, not yet set up as "`development environments`" with tools like [.buzz]*Ruby*, [.buzz]*Node.js*, [.buzz]*Python*, [.buzz]*Git*, [.buzz]*Pandoc*, [.buzz]*Vale* and the world of capabilities that these tools open up.
 // end::agent-guide[]
 
 [NOTE]
@@ -129,7 +130,7 @@ The next few sections are for users who want to understand the rationale and con
 [[tooling-overview]]
 === Tooling Overview
 
-The only real prerequisite for the "`Dockerized`" ("`containerized`") approach to establishing a robust DocOps environment, as provided in this project, is that you have Docker working on top of a [.term.term-unixlike]#Unix-like# [.term]#shell#<<gloss-shell,{gref}>>.
+The only real requirement for a "`Dockerized`" ("`containerized`") approach to establishing a robust DocOps environment, as provided in this project, is that you have Docker working on top of a [.term.term-unixlike]#Unix-like# [.term]#shell#<<gloss-shell,{gref}>>.
 
 It makes the most sense for users who need a consistent mix of tools across multiple projects;
 setting up a separate Docker image per tool is at least as complicated as a native install.
@@ -281,6 +282,12 @@ Prerequisites:;;
 This section is somewhat long but should move along quickly.
 All of these apps are critical, some are likely already available on your system, and this guide covers installing them on any major platform.
 
+[WARNING]
+====
+DocOps Box images require free space on your local disk.
+The `max:work` images are around 2.3 GB, and the `min:live` images are around 700 MB.
+====
+
 // tag::agent-prerequisite-guidance[]
 // tag::prerequisites-all-os[]
 [[prereq-terminal]]
@@ -295,24 +302,29 @@ Use VS Code's terminal inside the containerized environment; use an external ter
 
 If you are unaware of or unhappy with your terminal app, here are my recommendations per operating system.
 
-[[warp-terminal]]
+[[warp-wave-terminal]]
 ==== Warp and Wave
 
 By far my two favorite terminal apps are Warp and Wave.
+Both are free, open-source programs with optional AI integration, at a cost.
+
+[WARNING]
+Both Wave and Warp install with telemetry be enabled by default, and it is required for free AI use.
+Paid users can opt out of telemetry, as can free users not wishing to partake of the AI features.
 
-Both are freemium open-source models with generous free tiers.
+Warp has a fully AI-integrated terminal that can be a little bit overwhelming but provides excellent interactivity between terminal and [.term]#GUI#<<gloss-gui,{gref}>>.
 
-Warp has a fully integrated terminal that can be a little bit overwhelming.
+Wave's AI aspect is chat-only for now, so you have to copy and paste commands and output back and forth, though the chat can automatically read local files.
 
-Wave is a chat-only tool for now, so you have to copy and paste commands and output back and forth, though the chat can automatically read local files.
+Both are excellent terminal emulators _aside from or despite_ the optional AI tie-in.
 
 * link:https://www.warp.dev/terminal[Download Warp] (downloads for all platforms in page footer)
 * link:https://www.waveterm.dev/download[Download Wave]
 
 // end::prerequisites-all-os[]
 
-[[host-installs]]
-==== Host Terminal Apps
+[[os-terminals]]
+==== OS-specific terminal apps
 
 If you prefer to install from an app store or package manager, here are some good options on all three platforms.
 
@@ -656,7 +668,7 @@ To test that `dxbx` is working, run this command in your terminal:
 You should see a nicely formatted readout of available tools and be returned to your host shell prompt.
 
 [%collapsible]
-.What was that?]
+.What was that?
 ====
 The second half of the above command (`docops info`) is run inside any DocOps Box container for a readout of tool availability and versions.
 
@@ -1590,6 +1602,11 @@ Refers to any prompt-based program you interact with by typing commands into a t
 Most tools in the DocOps ecosystem are CLI tools.
 CLI is effectively a superset which includes _TUI_ applications.
 
+[[gloss-gui]]
+GUI::
+Short for _graphical user interface_, a program that presents interactive visual elements like windows, buttons, and menus.
+Most terminal apps are "`GUIs`"; CLIs run inside the terminal interface, but the app offers menus, tabs, or other external visual elements.
+
 [[gloss-tui]]
 TUI::
 For _text-based user interface_.
@@ -2346,26 +2363,37 @@ The only downside: you may miss them when stuck at a bare server Bash prompt, wh
 [[adr]]
 ==== Architecture Decision Rationale
 
+[[docker-compose]]
 Why Docker + Compose?::
 Raw `docker run` commands quickly grow unwieldy: volumes, ports, user IDs, environment variables, image tags, all of them manually specified each time.
 Docker Compose externalizes all of that into a versioned `{compose_config_file}`, making the run configuration reproducible and shareable in Git.
 +
 Fortunately, the breadth of DocOps use cases does not require a complex multi-service setup, so the Compose file is simple and approachable for users new to Docker.
 
+[[no-podman]]
+Why no Podman support?::
+Podman is a promising alternative to Docker that I simply don't have real experience with.
+So far my clients and colleagues have already had access to and often professional support for Docker.
+Adding Podman support seems like a worthy goal, but I have not investigated the complexity or the maintenance overhead it will add.
+See about <<tool-request,tool requests below>> if you would like to see this added.
+
+[[work-live]]
 Why separate `work` and `live` contexts?::
 Interactive daily work benefits from things that automated pipelines do not, such as Z shell, TUI text editors, and full terminal tooling.
 Including these in a `live` CI/CD image wastes build time and inflates image size.
 Separate contexts keep each image lean and purpose-built.
 +
 That said, you could also use one `max:work` image for both purposes early on if you don't wish to fuss about the distinction.
 
+[[named-volumes]]
 Why named volumes for all dependency caches?::
 Dependency trees for Ruby, Node.js, and Python all produce Linux-native artifacts (compiled gem extensions, Node binary modules, Python virtualenv symlinks) that are wrong-architecture or broken when accessed from the host filesystem on MacOS or Windows.
 Keeping them in named volumes (invisible to the host) removes that failure mode entirely and eliminates bind-mount overhead on MacOS.
 Keeping dependency files invisible to the host filesystem also keeps searches cleaner than if they were stashed in a directory under the project root.
 +
 Dependency caches are _disposable and fully reproducible_ `bundle install`, `npm install`, or `pip install` regenerates them in minutes.
 
+[[entrypoint]]
 Why an entrypoint script?::
 Docker images deployed to a registry cannot know the UID or GID of the user who will run them.
 Placing UID/GID reconciliation in the image's own `ENTRYPOINT` script (rather than baking it at build time or requiring a separate file in the user's project) satisfies all three requirements simultaneously:
@@ -2374,11 +2402,25 @@ it runs on every `docker run` or `docker compose run` invocation, works with pre
 The entrypoint detects the `HOST_UID` and `HOST_GID` environment variables (passed in by `{compose_config_file}`), adjusts the container user's identity to match, then drops privileges and executes the original command (`$CMD` or the default shell).
 On MacOS with Docker Desktop, the VM layer provides transparent ownership mapping and the entrypoint is a no-op (it does nothing and throws no error).
 
+[[tool-request]]
 Why no [your runtime here]?::
 The `max` images include Ruby, Node.js, and Python because they are the environments I repeatedly find myself using and recommending to clients.
 Tempted as I am to add Java, Go, and Rust, I have no real experience supporting these platforms and only sporadic need.
 Go, Haskell, and Rust applications typically compile to static binaries that run just fine on the host, such as Vale and Pandoc.
 Adding more runtimes would also bloat the image size and build time, and I want to keep the project focused on documentation operations rather than becoming a general-purpose development environment.
++
+_If you have a strong case for a runtime or tool_ not currently included that would likely be widely appreciated, link:https://github.com/DocOps/box/issues/new?labels=tool%20request[file a tool-request issue].
+I will consider adding it if it fits the project's scope and my experience, or at least I will document my reasons for declining and help you build a custom image with your tool included.
+
+pass:[<!-- vale DocOpsLab-Authoring.Spelling = NO -->]
+
+[[vibe-code]]
+Should we vibe code it?::
+Absolutely not.
+See link:https://docopslab.org/blog/vibe-coding-vs-programming/[my blog post] as well as link:https://passo.uno/tools-slop-is-a-problem/["`Most vibe-coded tools are not for you`"] from fellow traveler Fabrizio Ferri Benedetti for approved takes on the quality bar for shippable software.
+LLM/agent assistance is welcome, but everything gets fully reviewed and manually pressure tested.
+
+pass:[<!-- vale DocOpsLab-Authoring.Spelling = YES -->]
 
 [appendix]
 [[development]]