# 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

```powershell
# 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
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
```