From 56141389197a219a5c277b9195bc688fd0fb9ee1 Mon Sep 17 00:00:00 2001
From: reachableceo <charles@turnsys.com>
Date: Thu, 6 Aug 2026 14:24:38 -0500
Subject: [PATCH] docs(agents): document Redmine + Discourse CLI access

Both tracking systems have read/write CLI wrappers in ~/daytoday/ (Docker
containers backed by gitignored .env files). Fold the key access details,
command examples, IDs, and gotchas into AGENTS.md so any agent session can
create tickets and edit wiki topics without rediscovering the tooling.
---
 AGENTS.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index d807c48..8ba5106 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,6 +97,37 @@ checklists, or TODOs in repo files. Use Redmine tickets instead.
 5. **Link code to tickets** — ticket descriptions and notes should reference
    the relevant file paths in this repo (e.g., `dcinfra/ups/`).
 
+### CLI access (read + write)
+
+Tickets are managed via the `redmine` CLI wrapper in the `~/daytoday/redmine`
+workspace (external to this repo). Full command reference, patterns, and
+the subtask escape hatch live in `~/daytoday/redmine/AGENTS.md` — read it for
+anything beyond the basics.
+
+```bash
+# Connection sanity check (run first in any session):
+~/daytoday/redmine/bin/redmine whoami
+
+# Your queue (project 55):
+~/daytoday/redmine/bin/redmine list --assigned-to-me -p 55
+
+# Show / create / update / close:
+~/daytoday/redmine/bin/redmine show 367
+~/daytoday/redmine/bin/redmine create -p 55 -s "Subject" -d "desc"
+~/daytoday/redmine/bin/redmine update 367 -n "Done: committed in abc123" --done-ratio 100
+~/daytoday/redmine/bin/redmine close 367
+```
+
+Key IDs: project **55** (`technicaloperations`), user **5** (`reachableceo`).
+Statuses: New(1), In Progress(2), Resolved(3,closed), Feedback(4), Closed(5),
+Rejected(6). New subtasks go to **Feedback (4)**. Tracker **3** = Support.
+**Gotcha:** `create` has no `--parent` flag — to make a subtask, use the
+`python-redmine` escape hatch inside the container (see
+`~/daytoday/redmine/AGENTS.md`). Always `show` a ticket before updating it.
+
+The `.env` holding `REDMINE_URL`/`REDMINE_API_KEY` lives (gitignored) at
+`/home/reachableceo/projects/KNEL-AIMiddleware/redmine-cli/.env`.
+
 ## Documentation Workflow
 
 **Discourse is the source of truth for all knowledge docs.** After any work
@@ -116,12 +147,44 @@ session, an agent MUST:
 5. **Self-audit before commit.** Code changes must be internally consistent.
    Documentation changes go to Discourse, not git.
 
+### CLI access (read + write)
+
+Wiki topics are managed via the `discourse` CLI wrapper in the
+`~/daytoday/discourse` workspace (external to this repo). Full command
+reference, patterns, and the raw-API escape hatch live in
+`~/daytoday/discourse/AGENTS.md` — read it for anything beyond the basics.
+
+```bash
+# Connection sanity check (run first in any session):
+~/daytoday/discourse/bin/discourse whoami
+
+# List VP TechOps topics:
+~/daytoday/discourse/bin/discourse ls -c vp-techops
+
+# Show a topic / edit a wiki post (find post id via `show`):
+~/daytoday/discourse/bin/discourse show 297
+~/daytoday/discourse/bin/discourse update <post_id> -b "new markdown body"
+```
+
+VP TechOps = category **74**. Key topics: #296 (project overview), #297
+(ops status), #298 (audit log). The API user is trust-level 4 but **not
+admin** — admin-only ops (category creation, setting the wiki flag) will
+403; surface those to the user rather than retrying. **Gotcha:**
+`update`/`delete` take a post **id**, not a post number (see
+`~/daytoday/discourse/AGENTS.md`). Never create a new topic for an update to
+existing knowledge — edit the wiki post in place.
+
+The `.env` holding `DISCOURSE_URL`/`DISCOURSE_API_KEY`/`DISCOURSE_API_USERNAME`
+lives (gitignored) at `/home/reachableceo/projects/KNEL-AIMiddleware/discourse-cli/.env`.
+
 ## Key Scripts
 
 | Script | Purpose |
 |--------|---------|
 | [`tests/remote.sh`](tests/remote.sh) | **SSH chokepoint** — all Proxmox host + sandbox VM access routes here |
 | [`netinfra/dns-cluster-setup/remote-dns.sh`](netinfra/dns-cluster-setup/remote-dns.sh) | SSH chokepoint for DNS infra hosts (netinfra-01/02, tsrouter, netboot) |
+| `~/daytoday/redmine/bin/redmine` | Redmine CLI wrapper (ticket read/write via Docker container) |
+| `~/daytoday/discourse/bin/discourse` | Discourse CLI wrapper (wiki topic read/write via Docker container) |
 | [`tests/vm-validation.sh`](tests/vm-validation.sh) | Deploy + validate on sandbox VM |
 | [`tests/run-tests.sh`](tests/run-tests.sh) | Test suite |
 | [`netinfra/dns-cluster-setup/setup.sh`](netinfra/dns-cluster-setup/setup.sh) | DNS cluster replication |