Orchestrator/bahn/Confluence_Bot/AGENTS.md

Agent Instructions — Confluence Bot

Overview

This repo provides tools to analyze and maintain a Confluence space. As an AI agent, you can use these scripts to:

1. Export the page tree for analysis
2. Push new or updated content as pages
3. Check what pages exist
4. Read specific pages for context
5. Reorganize the page structure

Setup (First Time)

1. Ensure .secrets exists with a valid CONFLUENCE_TOKEN
2. Edit config.ps1 with the correct Confluence URL, space key, and root page ID
3. Test connection: powershell -ExecutionPolicy Bypass -File scripts/confluence-check.ps1

Workflow

Analyzing a Space

# 1. Export everything
powershell -ExecutionPolicy Bypass -File scripts/confluence-export.ps1

# 2. Read the exported files in data/export/pages/
# 3. Analyze structure via data/export/page-index.json

Publishing Content

1. Create .md files in the /pages/ directory
2. Use standard Markdown (headers, lists, bold, code blocks)
3. The filename or first # Heading becomes the page title
4. Run: powershell -ExecutionPolicy Bypass -File scripts/confluence-push.ps1

Reading Specific Pages

powershell -ExecutionPolicy Bypass -File scripts/confluence-read.ps1 -PageIds "123456,789012"

Important Notes

• All scripts use PowerShell (compatible with PS 5.1+)
• Authentication is via Personal Access Token (PAT)
• The token is loaded from .secrets file (never commit this!)
• Pages are created/updated idempotently (safe to run multiple times)
• Content comparison prevents unnecessary version bumps

Error Handling

• 401/403 → Token expired or insufficient permissions
• Connection failed → VPN required or wrong URL
• Page not found → Wrong page ID in config

File Structure

Confluence_Bot/
├── config.ps1              # Your Confluence settings
├── .secrets                # Token (gitignored)
├── pages/                  # Markdown files to push
├── data/                   # Exported data (gitignored)
│   ├── export/pages/       # Exported HTML + MD
│   └── pages/              # Read pages
└── scripts/
    ├── lib/confluence-api.ps1  # Shared API functions
    ├── confluence-export.ps1   # Full tree export
    ├── confluence-push.ps1     # Push markdown as pages
    ├── confluence-check.ps1    # List existing pages
    └── confluence-read.ps1     # Read specific pages