Merge branch 'main' into autoloop-workflow

Author: dsyme

.github/aw/actions-lock.json

@@ -45,6 +45,11 @@
       "version": "v0.56.2",
       "sha": "f1073c5498ee46fec1530555a7c953445417c69b"
     },
+    "github/gh-aw/actions/setup@v0.58.3": {
+      "repo": "github/gh-aw/actions/setup",
+      "version": "v0.58.3",
+      "sha": "08a903b1fb2e493a84a57577778fe5dd711f9468"
+    },
     "super-linter/super-linter@v8.5.0": {
       "repo": "super-linter/super-linter",
       "version": "v8.5.0",

docs/agentic-wiki-writer.md

@@ -4,7 +4,10 @@
 
 **Automatically generates and maintains GitHub wiki pages from your source code**
 
-The [Agentic Wiki Writer workflow](../workflows/agentic-wiki-writer.md?plain=1) keeps your project's GitHub wiki synchronized with the codebase. After each merged pull request (or on demand), it reads a `PAGES.md` template to understand what to document, then writes wiki pages directly from the source code.
+The [Agentic Wiki Writer workflow](../workflows/agentic-wiki-writer.md?plain=1) keeps your project's GitHub wiki synchronized with the codebase. Once a day (if any pull requests were merged to the default branch), it reads a `PAGES.md` template to understand what to document, then writes wiki pages directly from the source code. You can also trigger it manually on demand.
+
+> [!WARNING]
+> **The repository wiki must be initialized before running this workflow.** GitHub does not create the wiki git repository until at least one page exists. Go to your repository's **Wiki** tab and create a blank page (e.g. "Home") to initialize it. The workflow will fail with a git clone error if this step is skipped.
 
 ## Installation
 
@@ -22,18 +25,20 @@ This walks you through adding the workflow to your repository.
 
 ```mermaid
 graph LR
-    A[PR merged / manual trigger] --> B{PAGES.md exists?}
-    B -->|No| C[Generate PAGES.md template]
-    B -->|Yes| D[Read PAGES.md template]
-    C --> E[Save template to .github/agentic-wiki/]
-    D --> F[Identify changed files from PR]
-    F --> G[Read relevant source files]
-    G --> H[Write wiki pages]
-    H --> I[Push wiki pages]
-    I --> J[Create PR if source changes needed]
+    A[Daily schedule / manual trigger] --> B{Any merges today?}
+    B -->|No| C[Skip - no wiki update needed]
+    B -->|Yes| D{PAGES.md exists?}
+    D -->|No| E[Generate PAGES.md template]
+    D -->|Yes| F[Read PAGES.md template]
+    E --> G[Save template to .github/agentic-wiki/]
+    F --> H[Identify changed files from recent merges]
+    H --> I[Read relevant source files]
+    I --> J[Write wiki pages]
+    J --> K[Push wiki pages]
+    K --> L[Create PR if source changes needed]
 ```
 
-On the first run (or when `regenerate-template` is enabled), the workflow generates a `PAGES.md` template describing the wiki structure it will maintain. On subsequent runs it follows the template — reading only the source files relevant to the merged PR, then writing updated wiki content.
+On the first run (or when `regenerate-template` is enabled), the workflow generates a `PAGES.md` template describing the wiki structure it will maintain. On subsequent runs it follows the template — reading only the source files relevant to the recently merged PRs, then writing updated wiki content.
 
 ### Key Features
 
@@ -49,12 +54,201 @@ Trigger the workflow manually with `regenerate-template: true` to create the ini
 
 ### Configuration
 
-The workflow triggers automatically on every merged PR to the default branch. You can also trigger it manually from the Actions tab:
+The workflow runs once a day (around 4:22am UTC) and checks whether any pull requests were merged to the default branch in the last 24 hours. If no merges happened, it exits early with no work done. You can also trigger it manually from the Actions tab.
 
-- **`regenerate-template`** (`boolean`, default `false`) — Set to `true` to rebuild the `PAGES.md` template from scratch.
+You can adjust the cadence or event structure to suit your team's workflow. For example, to run immediately on every merge to the default branch (instead of waiting for the daily schedule), replace the `schedule: daily around 4:22` trigger with a `push` trigger:
+
+```yaml
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    ...
+```
+
+When using a `push` trigger, the agent will always run on every merge — there is no need for the "any merges today?" check.
+
+Or to run at a different time or cadence, change the schedule. For example, to run at 9am UTC every weekday:
+
+```yaml
+on:
+  schedule:
+    - cron: "0 9 * * 1-5"
+  workflow_dispatch:
+    ...
+```
 
 After editing the workflow file, run `gh aw compile` to update the compiled workflow and commit all changes to the default branch.
 
+Available inputs for manual dispatch:
+
+- **`regenerate-template`** (`boolean`, default `false`) — Set to `true` to rebuild the `PAGES.md` template from scratch.
+
+## PAGES.md Format
+
+The `PAGES.md` file at `.github/agentic-wiki/PAGES.md` is the single source of truth for your wiki structure. It is generated automatically on the first run and saved as a PR for you to review. After that, you can edit it freely to customize your documentation structure. You can also supply a `PAGES.md` yourself before the first run to pre-define the structure.
+
+### Header Hierarchy
+
+| Level | Purpose | Output |
+|-------|---------|--------|
+| H1 (`#`) | Top-level page | Separate `.md` file, top-level sidebar entry |
+| H2 (`##`) | Nested page | Separate `.md` file, indented under parent in sidebar |
+| H3 (`###`) | Deeply nested page | Separate `.md` file, further indented in sidebar |
+| H4+ (`####`) | Section within page | H2+ header in rendered page, not in sidebar nav |
+| H4+ with `+` (`####+`) | Sidebar section | H2+ header in page, included in sidebar nav |
+
+### Query Templates
+
+Use `*{ query }*` syntax to mark content that should be AI-generated:
+
+```markdown
+# Home
+
+*{ Provide an overview of this project }*
+
+## Architecture
+
+*{ Describe the system architecture and key design decisions }*
+```
+
+Static text is preserved as-is:
+
+```markdown
+# Getting Started
+
+This guide will help you set up the project.
+
+*{ List the installation steps }*
+
+For more help, see the troubleshooting section.
+```
+
+### Sidebar Sections
+
+By default, H4+ headers become sections within a page but don't appear in the sidebar. Add `+` after the hashes to include them in sidebar navigation:
+
+```markdown
+# API Reference
+
+*{ Overview of the API }*
+
+####+ Authentication
+*{ Describe auth flow }*
+
+####+ Rate Limits
+*{ Describe rate limiting }*
+
+#### Internal Details
+*{ Implementation details - not shown in sidebar }*
+```
+
+This generates:
+- Sidebar: `API Reference` with nested links to `#Authentication` and `#Rate Limits`
+- Page: All three sections rendered as H2 headers
+
+### Header Normalization
+
+Sections (H4–H6) are normalized when rendered to individual pages:
+
+| In PAGES.md | In rendered page |
+|-------------|-----------------|
+| `####` / `####+` | `##` |
+| `#####` | `###` |
+| `######` | `####` |
+
+Every page starts with an implicit H1 (the page title, rendered by GitHub from the filename). Sections start at H2.
+
+### Slug Generation
+
+Page and section slugs are generated from titles:
+- Spaces → hyphens
+- Special characters removed (apostrophes, parentheses, question marks, etc.)
+- Multiple hyphens collapsed
+
+| Title | Slug |
+|-------|------|
+| `Getting Started` | `Getting-Started` |
+| `What's New?` | `Whats-New` |
+| `API Reference (v2)` | `API-Reference-v2` |
+
+### Complete Example
+
+```markdown
+# Home
+
+Welcome to the project documentation.
+
+*{ Provide a brief overview of the project }*
+
+# Architecture
+
+*{ Describe the high-level architecture }*
+
+## Frontend
+
+*{ Describe the frontend stack }*
+
+### Components
+
+*{ List major React components }*
+
+####+ State Management
+*{ Explain how state is managed }*
+
+####+ Routing
+*{ Describe the routing setup }*
+
+## Backend
+
+*{ Describe the backend architecture }*
+
+### API
+
+*{ Document the REST API }*
+
+####+ Endpoints
+*{ List all endpoints }*
+
+# Getting Started
+
+*{ Write a getting started guide }*
+
+#### Prerequisites
+*{ List prerequisites }*
+
+#### Installation
+*{ Installation steps }*
+```
+
+**Output files:**
+
+| File | Content |
+|------|---------|
+| `Home.md` | H1 title + overview content |
+| `Architecture.md` | H1 title + architecture content |
+| `Frontend.md` | H1 title + frontend content + State Management (H2) + Routing (H2) sections |
+| `Components.md` | H1 title + components content |
+| `Backend.md` | H1 title + backend content |
+| `API.md` | H1 title + API content + Endpoints (H2) section |
+| `Getting-Started.md` | H1 title + guide content + Prerequisites (H2) + Installation (H2) sections |
+| `_Sidebar.md` | Auto-generated navigation |
+
+**Generated sidebar:**
+
+```markdown
+- [[Home|Home]]
+- [[Architecture|Architecture]]
+  - [[Frontend|Frontend]]
+    - [[State Management|Frontend#State-Management]]
+    - [[Routing|Frontend#Routing]]
+    - [[Components|Components]]
+  - [[Backend|Backend]]
+    - [[API|API]]
+      - [[Endpoints|API#Endpoints]]
+- [[Getting Started|Getting-Started]]
+```
+
 ## Learn More
 
 - [Agentic Wiki Writer source workflow](https://github.com/githubnext/agentics/blob/main/workflows/agentic-wiki-writer.md)

workflows/agentic-wiki-coder.md

@@ -110,6 +110,22 @@ Parse the `pages` array from the JSON. Each entry contains:
 
 Also extract `sender.login` from the event payload for the feedback loop check in Step 0b.
 
+### 0a-ii. Construct wiki diff URLs
+
+For each page in the event, construct the diff URL using this pattern:
+
+```
+{html_url}/_compare/{sha}
+```
+
+For example, if `html_url` is `https://github.com/owner/repo/wiki/My-Page` and `sha` is `abc123`, the diff URL is:
+
+```
+https://github.com/owner/repo/wiki/My-Page/_compare/abc123
+```
+
+Save these diff URLs — you will need them for the PR/issue body in Step 7.
+
 ### 0b. Check for feedback loops
 
 Check the `sender.login` field from the event payload (extracted in Step 0a). If the sender login is `github-actions[bot]`, this edit was made by the `agentic-wiki-writer` workflow (which commits as `github-actions[bot]`). Call the `noop` safe-output with "Wiki edit was made by github-actions[bot] — skipping to prevent feedback loop with agentic-wiki-writer" and **stop**.
@@ -132,13 +148,29 @@ If this directory does not exist or is empty, run `echo "FATAL: wiki not pre-clo
 
 Do NOT attempt to clone the wiki yourself — `GITHUB_TOKEN` is not available in the sandbox.
 
-### 1b. Read changed pages
+### 1b. Get wiki diffs
+
+For each changed page, get the actual diff content from the wiki clone. Run `git log` and `git diff` in `/tmp/gh-aw/wiki/` to extract what changed:
+
+```bash
+cd /tmp/gh-aw/wiki && git show --format="%H %s" --stat {sha}
+```
+
+```bash
+cd /tmp/gh-aw/wiki && git diff {sha}~1 {sha} -- "*.md"
+```
+
+If the page was newly created (`action` is `"created"`), the parent commit may not contain the file, so use `git show {sha} -- {Page-Name}.md` instead.
+
+Save the diff output for each page — you will include it (or a summary of it) in the PR/issue body in Step 7.
+
+### 1c. Read changed pages
 
 Read **each changed wiki page** identified in the event payload (Step 0a) from `/tmp/gh-aw/wiki/`. The files are named `Page-Name.md` (title with spaces replaced by hyphens).
 
 **Focus on the specific pages from the event.** These are the pages that triggered this run. Read each one carefully — these are your primary input.
 
-### 1c. Read surrounding pages for context
+### 1d. Read surrounding pages for context
 
 Read other wiki pages that might provide context — especially the Home page and any pages that link to or from the changed pages. This helps you understand the broader documentation context.
 
@@ -259,13 +291,24 @@ Keep it under 70 characters. Examples:
 
 ### PR body
 
-Structure the body as follows:
+Structure the body as follows. The wiki change that triggered the work MUST be the most prominent part — a reviewer should immediately see what wiki edit inspired this code change.
 
 ```markdown
-## Wiki Changes
+## Wiki Change
+
+**[Page Name](html_url)** — [view diff](diff_url)
 
-This PR implements code changes based on edits to the following wiki pages:
-- [Page Name](html_url) — <brief description of what changed>
+<Include the wiki diff here. If the diff is small (under ~40 lines), show it in full inside a diff code block. If it is large, write a concise summary of the key changes (what was added, removed, or modified) and link to the full diff.>
+
+<details><summary>Wiki diff</summary>
+
+```diff
+<the actual diff output from git diff>
+```
+
+</details>
+
+<For multiple pages, repeat the above block for each page.>
 
 ## Implementation Summary
 
@@ -286,6 +329,12 @@ This PR implements code changes based on edits to the following wiki pages:
 - [ ] `bunx tsc --noEmit` passes
 ```
 
+**Small vs large diffs:**
+- **Small diffs (under ~40 lines):** Show the full diff directly in the body (not inside a `<details>` block) so reviewers see it immediately.
+- **Large diffs (40+ lines):** Write a 2-4 sentence summary of the functional changes above the fold, then put the full diff inside a `<details>` block.
+
+This same structure applies if the safe-output falls back to creating an issue instead of a PR (e.g., due to protected files). The issue body should use the identical format so the wiki diff is always front and center.
+
 ## Step 8: Update memory
 
 After creating the PR (or after deciding on noop), update memory files in MEMORY_DIR.