docs: add Document Map index + Entertainment section to agent context

- AGENT_Context opens with a generated Document Map (section → line ranges)
- gen-docs.sh: new gen_docmap block, self-referential (converges to a
  fixed point so line numbers stay accurate)
- new '## 8. Entertainment Module' section (CLI, lib, plugins, config,
  scheduler, pointers); renumber following sections 8-13 -> 9-14
- AGENTS.md: reference the Document Map; document the make check/gen gate

AGENTS.md

@@ -6,7 +6,7 @@ Personal bootstrap & homelab toolkit for Debian/Ubuntu (Bash). `install.sh` boot
 
 CRITICAL: real guidance lives in DOC/. When you encounter a reference below, use your Read tool to load it on a need-to-know basis — do NOT preemptively load all of them. Once loaded, treat the content as mandatory instructions.
 
-- @DOC/AGENT_Context_Project.md — project overview, directory structure, `pos` dispatch table, "How to modify" table. Read FIRST for any non-trivial task.
+- @DOC/AGENT_Context_Project.md — project overview, directory structure, `pos` dispatch table, "How to modify" table. Read FIRST for any non-trivial task. It opens with a **Document Map** (auto-generated line ranges for every section) — use it to jump straight to the relevant section.
 - @DOC/DEV.md — conventions, verification, and the "Adding a new Feature/App/Tool" checklists. Read before creating or changing code/docs.
 - @DOC/POS.md — `pos` CLI reference (dispatcher + every command). Read when working on `bin/pos*` scripts or their docs.
 - @DOC/README.md — index of all docs. Read to find the right doc.
@@ -14,4 +14,4 @@ CRITICAL: real guidance lives in DOC/. When you encounter a reference below, use
 ## Quick facts
 
 - Each tool is `bin/pos-<category>-<command>`; `bin/pos` dispatches via smart arg matching; bash completion derives from filenames.
-- Verify edits with `bash -n` on touched scripts and smoke-test dispatch; keep line counts in `DOC/AGENT_Context_Project.md`'s file table in sync.
+- Verify edits with `make check` (runs `bash -n` + the generated-doc sync gate). Generated sections (dispatch table, file table, line counts, completion flags, this doc's Document Map) are code-derived — after changing `bin/pos-*`, `lib/*`, or `completions/`, run `make gen` and commit the refreshed output.

DOC/AGENT_Context_Project.md

@@ -4,6 +4,27 @@
 
 ---
 
+## Document Map
+
+> Auto-generated section index (line ranges). Run `make gen` to refresh.
+
+<!-- GEN:START docmap -->
+| ## 1. Project Overview | 28–43 |
+| ## 2. Directory Structure | 44–164 |
+| ## 3. Installation Flow | 165–216 |
+| ## 4. The `pos` CLI System | 217–273 |
+| ## 5. Shared Library — `lib/common.sh` | 274–304 |
+| ## 6. Docker Compose / ScaleTail | 305–347 |
+| ## 7. Optional Apps (`apps/`) | 348–377 |
+| ## 8. Entertainment Module | 378–391 |
+| ## 9. Systemd Services | 392–402 |
+| ## 10. Configuration Files | 403–426 |
+| ## 11. Coding Conventions | 427–459 |
+| ## 12. Development Workflow | 460–511 |
+| ## 13. Key File Quick Reference | 512–553 |
+| ## 14. Common Tasks for Agents | 554–578 |
+<!-- GEN:END docmap -->
+
 ## 1. Project Overview
 
 **Linux_post_install** is a personal bootstrap and homelab toolkit for Debian/Ubuntu. One command turns a bare install into a fully productive machine:
@@ -354,7 +375,21 @@ ScaleTail provides 119+ Docker Compose templates with a Tailscale sidecar patter
 
 ---
 
-## 8. Systemd Services
+## 8. Entertainment Module
+
+Public-API "entertainment" plugins (weather, joke, gold) that can auto-send their output to Telegram on a schedule.
+
+- **CLI:** `pos entertainment {config|enable|disable|send|status}` — see the dispatch table in §4 and POS.md [entertainment](#entertainment).
+- **Library:** `lib/entertainment-lib.sh` — config-file helpers, ENABLED-list parsing, plugin lookup, and scheduler sync (systemd user timers, crontab fallback).
+- **Plugins:** `entertainment/*.sh` — standalone scripts that fetch a public API and **print the message to stdout** (what gets sent). Each declares its name with a `# POS_PLUGIN: <name>` header; a new plugin is auto-discovered.
+- **Config:** `~/.config/linux_post_install/entertainment.env` (ENABLED auto-trigger list, weather location). Template: `config/entertainment.env`, auto-installed by postinstall.
+- **Sending:** `pos entertainment send <plugin> [--print] [--markdown]` runs the plugin and delivers via `pos communication telegram --send`.
+- **Auto-trigger:** `pos entertainment enable <plugin> <interval>` writes the plugin into ENABLED and syncs a systemd user timer (allowed intervals: `5m 10m 15m 30m 45m hourly 2h 6h 12h daily weekly`, or `OnCalendar=…`); `disable` removes it.
+- **Docs:** DEV.md "Adding an Entertainment Plugin" (§1 step list) and POS.md [entertainment](#entertainment).
+
+---
+
+## 9. Systemd Services
 
 | Service | File | Purpose |
 |---------|------|---------|
@@ -365,7 +400,7 @@ All `.service` files in `systemd/` are automatically copied to `/etc/systemd/sys
 
 ---
 
-## 9. Configuration Files
+## 10. Configuration Files
 
 ### Gitignored Secrets
 
@@ -389,7 +424,7 @@ System-wide flag store at `/usr/local/share/linux_post_install/flags/`:
 
 ---
 
-## 10. Coding Conventions
+## 11. Coding Conventions
 
 ### Script Standards
 
@@ -422,7 +457,7 @@ System-wide flag store at `/usr/local/share/linux_post_install/flags/`:
 
 ---
 
-## 11. Development Workflow
+## 12. Development Workflow
 
 ### Adding a New Feature
 
@@ -474,7 +509,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 
 ---
 
-## 12. Key File Quick Reference
+## 13. Key File Quick Reference
 
 | File | Lines | Purpose |
 |------|-------|---------|
@@ -516,7 +551,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 
 ---
 
-## 13. Common Tasks for Agents
+## 14. Common Tasks for Agents
 
 | Task | Where to Edit |
 |------|---------------|

scripts/gen-docs.sh

@@ -89,6 +89,28 @@ gen_posflags() {
     done
 }
 
+# Section index of AGENT_Context itself: maps each "## " heading to its
+# line range. Excludes the "Document Map" heading (this block).
+gen_docmap() {
+    local file="$ctx" lines=() sections=() line n title i last
+    mapfile -t lines < <(grep -nE '^## ' "$file")
+    for line in "${lines[@]}"; do
+        title="${line#*:}"
+        [[ "$title" == "## Document Map" ]] && continue
+        sections+=("$line")
+    done
+    for i in "${!sections[@]}"; do
+        n="${sections[$i]%%:*}"
+        title="${sections[$i]#*:}"
+        if [ "$i" -eq $((${#sections[@]} - 1)) ]; then
+            last=$(wc -l < "$file")
+        else
+            last=$(( ${sections[$((i + 1))]%%:*} - 1 ))
+        fi
+        printf '| %s | %s–%s |\n' "$title" "$n" "$last"
+    done
+}
+
 # ── Replace (write) or verify (check) one marker block ──────────
 regen_block() {
     local file="$1" name="$2"
@@ -135,4 +157,16 @@ regen_block "$ctx" selfcontained
 regen_block "$comp" posflags
 regen_block "$ctx" filetable
 
+# docmap is self-referential: its own block size shifts the section line
+# numbers below it — regenerate until stable (converges in 2-3 passes).
+regen_block "$ctx" docmap
+if [ "$mode" = "write" ]; then
+    for _ in 1 2 3 4 5; do
+        prev="$(sed -n '/<!-- GEN:START docmap -->/,/<!-- GEN:END docmap -->/p' "$ctx")"
+        regen_block "$ctx" docmap
+        after="$(sed -n '/<!-- GEN:START docmap -->/,/<!-- GEN:END docmap -->/p' "$ctx")"
+        [ "$prev" = "$after" ] && break
+    done
+fi
+
 echo "gen-docs: $mode OK"