Remaining polish and P2 backlog items

AGENTS.md

@@ -4,8 +4,14 @@
 This repository builds `conf` (`confluence-sync`), a Go CLI that syncs Confluence pages with local Markdown files.
 
 ## Source Of Truth
-- Primary plan: `agents/plans/confluence_sync_cli.md`
-- If implementation details are unclear, update the plan first, then implement.
+- Canonical specs:
+  - `openspec/project.md`
+  - `openspec/specs/*/spec.md`
+- Narrative summaries:
+  - `docs/specs/prd.md`
+  - `docs/specs/technical-spec.md`
+  - `docs/specs/README.md`
+- If behavior changes, update the canonical specs first, then implement.
 
 ## Intended Usages
 
@@ -14,7 +20,7 @@ This project supports two primary sync workflows for agents:
 ### 1. Human-in-the-Loop (Agent as Writer)
 The agent focus on Markdown content; the human runs `conf` commands.
 - **Agent Task**: Edit `.md` files, run `conf validate` to check work.
-- **Safety**: Do not touch `id`, `space`, or `version` in frontmatter.
+- **Safety**: Do not touch sync-managed frontmatter keys such as `id`, `version`, `created_by`, `created_at`, `updated_by`, or `updated_at`.
 
 ### 2. Full Agentic Use (Autonomous Sync)
 The agent manages the full sync cycle.
@@ -26,13 +32,18 @@ The agent manages the full sync cycle.
 
 - Immutable frontmatter keys:
   - `id`
-  - `space`
 - Mutable-by-sync frontmatter keys:
   - `version`
+  - `created_by`
+  - `created_at`
+  - `updated_by`
+  - `updated_at`
 - User-editable frontmatter keys:
+  - `title`
   - `state` (can be `draft` or `current`. Omitted means `current`. Cannot be set back to `draft` once published remotely).
   - `status` (Confluence "Content Status" visual lozenge, e.g., "Ready to review").
   - `labels` (array of strings for Confluence page labels).
+- Space identity is stored in `.confluence-state.json` and workspace context, not in frontmatter.
 - Remote deletions are hard-deleted locally during `pull` (recovery is via Git history).
 - `.confluence-state.json` is local state and must stay gitignored.
 
@@ -43,6 +54,15 @@ The agent manages the full sync cycle.
 - `validate`/`push` run with strict resolution (`ErrUnresolved` => conversion failure).
 - `validate` must use the same strict reverse-conversion profile and hook adapters as `push`.
 - Hooks return mapping decisions only; sync orchestration owns downloads/uploads and file writes/deletes.
+- Diagram contract:
+  - PlantUML is supported as a first-class `plantumlcloud` Confluence extension.
+  - Mermaid is preserved as fenced code / ADF `codeBlock` content, not a rendered Confluence diagram macro.
+  - `validate` should warn before push when Mermaid fences are present so the downgrade is explicit.
+- Extension/macro support contract:
+  - PlantUML: rendered round-trip support via the custom `plantumlcloud` handler.
+  - Mermaid: preserved-but-not-rendered only; keep it as fenced code and expect an ADF `codeBlock` on push.
+  - Raw `adf:extension` payloads: best-effort, low-level preservation fallback for extension nodes without a repo-specific handler; not a verified end-to-end round-trip guarantee.
+  - Unknown Confluence macros/extensions: not a first-class supported authoring target; they may only survive through best-effort raw ADF preservation, and Confluence can still reject them on push. Validate any such workflow in a sandbox before relying on it.
 
 ## Git Workflow Requirements
 - `push` uses an ephemeral sync branch: `sync/<SpaceKey>/<UTC timestamp>`.
@@ -72,7 +92,8 @@ The agent manages the full sync cycle.
 Validation failures must stop `push` immediately.
 
 ## Command Model
-- Commands: `init`, `pull`, `push`, `validate`, `diff`, `search`.
+- Commands: `init`, `pull`, `push`, `recover`, `status`, `clean`, `prune`, `validate`, `diff`, `relink`, `version`, `doctor`, `search`.
+- `status` reports Markdown page drift only; attachment-only changes should be checked with `git status` or `conf diff`.
 - `[TARGET]` parsing rule:
   - Ends with `.md` => file mode.
   - Otherwise => space mode (`SPACE_KEY`).
@@ -87,6 +108,10 @@ Validation failures must stop `push` immediately.
   - `--label LABEL` — filter by label (repeatable).
   - `--heading TEXT` — restrict to sections under matching headings.
   - `--reindex` — force full rebuild.
+  - `--result-detail full|standard|minimal` — control payload size/detail.
+  - `--created-by USER` / `--updated-by USER` — filter by creator or last updater.
+  - `--created-after DATE` / `--created-before DATE` — bound created timestamps.
+  - `--updated-after DATE` / `--updated-before DATE` — bound updated timestamps.
   - `--list-labels` / `--list-spaces` — facet discovery.
   - `--format text|json|auto` — output format (auto: TTY→text, pipe→json).
   - `--limit N` (default 20) — max results.
@@ -127,5 +152,5 @@ Validation failures must stop `push` immediately.
   - Round-trip Markdown <-> ADF golden tests.
 
 ## Docs Maintenance
-- Keep `README.md` aligned with current plan and command behavior.
-- Keep this file aligned with `agents/plans/confluence_sync_cli.md`.
+- Keep `README.md`, `docs/usage.md`, `docs/automation.md`, and `docs/compatibility.md` aligned with the OpenSpec files.
+- Keep this file aligned with `openspec/project.md` and `openspec/specs/*/spec.md`.

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to `conf` are documented here. This changelog focuses on
+user-visible sync semantics — hierarchy rules, attachment handling, validation
+strictness, and cleanup/recovery behavior.
+
+## [Unreleased]
+
+### Added
+- Push preflight (`--preflight`) now probes remote capabilities and reports
+  degraded modes (content-status, folder API) before execution.
+- Push preflight shows exact planned page and attachment mutations.
+- Generated AGENTS.md uses a single unified workflow instead of split
+  human-in-the-loop / autonomous modes.
+- Recovery artifact inspection via `conf recover` command.
+- No-op commands now explain why nothing changed.
+- Destructive operation previews show exact pages/attachments targeted.
+- Feature/tenant compatibility matrix in documentation (`docs/compatibility.md`).
+
+### Changed
+- Generated AGENTS.md frontmatter guidance no longer lists `space` as an
+  immutable key (it was removed from frontmatter).
+- README includes beta maturity notice.
+
+### Fixed
+- (none yet)
+
+### Removed
+- (none yet)
+
+## Sync Semantics Change Tracking
+
+Changes in the following categories are always noted explicitly:
+
+- **Hierarchy rules**: How pages are organized in directories, folder vs page
+  parent handling, path move detection.
+- **Attachment handling**: Upload/delete/preserve logic, orphan asset cleanup,
+  asset path conventions.
+- **Validation strictness**: What `validate` and `push` reject, Mermaid
+  warnings, frontmatter schema enforcement.
+- **Cleanup/recovery semantics**: Sync branch lifecycle, snapshot ref
+  retention, recovery metadata, `clean` behavior.

README.md

@@ -2,12 +2,15 @@
 
 Write docs like code. Publish to Confluence with confidence. ✍️
 
+> **Beta** — `conf` is under active development. Core sync workflows (pull, push, validate, diff, status) are tested against live Confluence tenants, but edge cases remain. Pin a specific version for production use and test changes in a sandbox space before relying on new releases.
+
 `conf` is a Go CLI that keeps Confluence pages and local Markdown in sync, so teams can use editor + Git + CI workflows without giving up Confluence as the publishing platform.
 
 ## Why teams use `conf` ✨
 - 📝 Markdown-first authoring with Confluence as the destination.
 - 🛡️ Safe sync model with validation before remote writes.
 - 👀 Clear preview step via `conf diff` before push.
+- 🔎 Local full-text search across synced Markdown with SQLite or Bleve backends.
 - 🤖 Works in local repos and automation pipelines.
 
 ## Install 🛠️
@@ -33,8 +36,9 @@ conf init
 ```
 
 `conf init` prepares Git metadata, `.gitignore`, and `.env` scaffolding, and creates an initial commit when it initializes a new Git repository.
+If `ATLASSIAN_*` or legacy `CONFLUENCE_*` credentials are already set in the environment, `conf init` writes `.env` from them without prompting.
 
-`conf pull` mirrors Confluence hierarchy locally by placing folders and child pages in nested directories. Pages with children use `<Page>/<Page>.md` so they are distinct from pure folders.
+`conf pull` mirrors Confluence hierarchy locally by placing folders and child pages in nested directories. Pages with children use `<Page>/<Page>.md` so they are distinct from pure folders. Leaf-page title renames can keep the existing Markdown path when the effective parent directory is unchanged, but pages that own subtree directories move when their self-owned directory segment changes. Hierarchy moves and ancestor/path-segment sanitization changes are surfaced as `PAGE_PATH_MOVED` notes in `conf pull`/`conf diff`, and `conf status` previews tracked moves before the next pull.
 
 ## Quick flow 🔄
 > ⚠️ **IMPORTANT**: If you are developing `conf` itself, NEVER run sync commands against real Confluence spaces in the repository root. This prevents accidental commits of synced documentation. Use a separate sandbox folder.
@@ -57,20 +61,34 @@ conf push ENG --on-conflict=cancel
 ```
 
 ## At a glance 👀
-- Commands: `init`, `init agents [TARGET]`, `pull [TARGET]`, `push [TARGET]`, `validate [TARGET]`, `diff [TARGET]`, `relink [TARGET]`
+- Commands: `init`, `init agents [TARGET]`, `pull [TARGET]`, `push [TARGET]`, `recover`, `status [TARGET]`, `clean`, `validate [TARGET]`, `diff [TARGET]`, `relink [TARGET]`, `search QUERY`
 - Version: `conf version` or `conf --version`
 - Target rule: `.md` suffix means file mode; otherwise space mode (`SPACE_KEY`)
 - Required auth: `ATLASSIAN_DOMAIN`, `ATLASSIAN_EMAIL`, `ATLASSIAN_API_TOKEN`
+- Extension support: PlantUML is the only first-class rendered extension handler; Mermaid is preserved as code, and raw `adf:extension` / unknown macro handling is best-effort and should be sandbox-validated before relying on it
+- Status scope: `conf status` reports Markdown page drift only; use `git status` or `conf diff` for attachment-only changes
 - Label rules: labels are trimmed, lowercased, deduplicated, and sorted; empty labels and labels containing whitespace are rejected
+- Search filters: `--space`, repeatable `--label`, `--heading`, `--created-by`, `--updated-by`, date bounds, and `--result-detail`
 - Git remote is optional (local Git is enough)
 
 ## Docs 📚
 - Usage and command reference: `docs/usage.md`
-- Automation and CI behavior: `docs/automation.md`
+- Feature and tenant compatibility matrix: `docs/compatibility.md`
+- Automation, CI behavior, and live sandbox smoke-test runbook: `docs/automation.md`
+- Changelog: `CHANGELOG.md`
 - Security policy: `SECURITY.md`
 - Support policy: `SUPPORT.md`
 - License: `LICENSE`
 
+## Extension and macro support 🧩
+
+| Item | Support level | What `conf` does | Notes |
+|------|---------------|------------------|-------|
+| PlantUML (`plantumlcloud`) | Rendered round-trip support | Pull converts the Confluence extension into Markdown with a managed `adf-extension` wrapper and `puml` body; push reconstructs the Confluence macro. | This is the only first-class custom extension handler in the repo today. |
+| Mermaid | Preserved but not rendered | Keeps Mermaid as fenced code in Markdown and pushes it back as an ADF `codeBlock` with `language: mermaid`. | `conf validate`/`conf push` warn with `MERMAID_PRESERVED_AS_CODEBLOCK` so the render downgrade is explicit. |
+| Raw ADF extension preservation | Best-effort preservation only | Unhandled extension nodes can fall back to raw ```` ```adf:extension ```` JSON blocks so the original ADF payload can be carried through Markdown with minimal interpretation. | This is a low-level escape hatch, not a rendered feature contract or a verified end-to-end round-trip guarantee. Validate any workflow that depends on it in a sandbox before relying on it. |
+| Unknown Confluence macros/extensions | Unsupported as a first-class feature | `conf` does not ship custom handlers for unknown macros, beyond whatever best-effort raw ADF preservation may be possible for some remote extension payloads. | Do not assume unknown macros will round-trip or render correctly. Push can still fail if Confluence rejects the macro or if the instance does not have the required app installed; sandbox validation is recommended before depending on this path. |
+
 ## Development 🧑‍💻
 - `make build`
 - `make test`