@ngocsangairvds/vsaf 3.1.26 → 3.2.1

package/tools/vds-scripts/confluence_orchestrator/Dockerfile

@@ -0,0 +1,19 @@
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim
+
+# Install uv
+RUN apt-get update && apt-get install -y curl ca-certificates && rm -rf /var/lib/apt/lists/* \
+    && curl -LsSf https://astral.sh/uv/install.sh | sh && echo "export PATH=\"$HOME/.cargo/bin:$PATH\"" >> /etc/profile
+
+WORKDIR /app
+COPY confluence_orchestrator/pyproject.toml /app/
+COPY confluence_orchestrator/uv.lock /app/
+
+# Sync deps (frozen)
+RUN /root/.cargo/bin/uv sync --frozen
+
+# Copy sources
+COPY confluence_orchestrator/src /app/src
+
+# Default command: run CLI help via uvx
+CMD ["/root/.cargo/bin/uvx", "vds-confluence-cli", "--help"]

package/tools/vds-scripts/confluence_orchestrator/README.md

@@ -0,0 +1,412 @@
+# VDS Confluence Orchestrator
+
+Python toolkit for Confluence operations using the `atlassian-python-api` SDK. The project closely mirrors the existing
+git orchestrator: uv-managed environment, Typer CLI, httpx client with structured logging, and JSON/Markdown run
+reports.
+
+## Quick Start
+
+```bash
+cd vds-scripts
+# Optional: sync every orchestrator once
+./scripts/bootstrap_uv.sh
+
+# Package-specific sync & tests
+uv sync --project confluence_orchestrator --extra dev
+uv run --project confluence_orchestrator pytest
+```
+
+Run the CLI directly (uv automatically loads the project environment once it has been synced at least once):
+
+```bash
+uv run --project confluence_orchestrator vds-confluence-cli --help
+```
+
+**Agent-friendly output**
+- When using `vds-cli`, pass Typer flags after `--` (e.g. `vds-cli confluence -- --json-only content ...`).
+- `--json-only` prints JSON to stdout and skips reports/markdown (logging suppressed).
+- `--no-reports` keeps normal console output while avoiding filesystem writes.
+
+Common commands (short form):
+```bash
+uv run --project confluence_orchestrator vds-confluence-cli content page 99647801 --server external --expand body.storage
+uv run --project confluence_orchestrator vds-confluence-cli export page --page-id 99647801 --output page.pdf
+```
+
+Via vds-cli router:
+```bash
+uv run --project vds_cli vds-cli confluence -- content page 99647801 --server external --expand body.storage
+```
+
+Full command examples:
+```bash
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli --help
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli get 99647801 --server external -- --strip-markup
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content page 99647801 --server external --expand body.storage
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content create-page --space TTTC --title "Automation" --body-file ./examples/page_storage.html
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content add-attachment 99647801 --file ./diagram.png --comment "Latest architecture diagram"
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content delete-attachment 99647801 --filename Current_Architecture_Reference.pdf
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli batch-native scan --cql "space = TTTC" --limit 10 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli webhook-native create --name "Notify" --url https://example.com/hook --event page_created --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli space-permissions get --space-key TTTC --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli space-permissions set --space-key TTTC --group "confluence-users" --operation read --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli space-management archive --space-key TTTC --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli space-management trash-list --space-key TTTC --limit 25 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli space-management trash-remove --space-key TTTC --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli group list --limit 50 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli group members --group "confluence-users" --limit 100 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli user get --username testuser --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli user get --userkey key123 --expand status,details --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli user password --username testuser --new-password "newpass123" --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli user group-add --username testuser --group "confluence-users" --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli user group-remove --username testuser --group "confluence-users" --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli export page --page-id 99647801 --output page.pdf
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli export space --space-key TTTC --export-type pdf --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli draft get --page-id 12345 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli draft list --space-key TTTC --limit 50 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli draft remove --page-id 12345 --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content ancestors 99647801 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content move 99647801 --target-title "Parent" --position append --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content tables 99647801 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content regex 99647801 --pattern "\d+" --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli content restrictions 99647801 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli history get --page-id 99647801 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli history version --page-id 99647801 --version 2 --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli history remove --page-id 99647801 --version 2 --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli cache statistics --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli cache flush --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli cache flush --cache-name "com.gliffy.cache.gon" --yes --json
+uv run --project confluence_orchestrator python -m confluence_orchestrator.cli cache size --json
+```
+
+The unified `vds_cli` still routes `confluence` commands through this project, so the usual workflow is:
+
+```bash
+uv run --project vds_cli vds-cli env load
+uv run --project vds_cli vds-cli confluence get 99647801 --server external -- --strip-markup
+```
+
+Run reports are written to `vds-scripts/reports/confluence_runs/YYYY/MM/DD/<timestamp>.json` (plus Markdown unless
+`--no-markdown` is used).
+
+## Linting
+
+We use Ruff for linting/formatting:
+
+```bash
+uv run --extra dev ruff check
+uv run --extra dev ruff format
+```
+
+## Project Layout
+
+- `src/confluence_orchestrator/config.py` – environment loader (`~/.vds/.env` + repo `.env`)
+- `src/confluence_orchestrator/http.py` – shared httpx client with retry/backoff
+- `src/confluence_orchestrator/cli.py` – Typer CLI bridging legacy bash scripts **and** exposing native `content`
+  subcommands
+- `src/confluence_orchestrator/content.py` – REST v1 helper layer (read + write: pages, templates, attachments,
+  attachment deletion by filename/ID)
+- `src/confluence_orchestrator/content_v2.py` – REST v2 adapter (read-only pages/templates/search)
+- `src/confluence_orchestrator/orchestration.py` – Batch polling + webhook management utilities
+- `src/confluence_orchestrator/reporting.py` – JSON/Markdown run reports
+- `tests/` – pytest suite using httpx MockTransport and Typer CliRunner
+
+## Available Commands
+
+### Search Operations
+
+- **`search`** - CQL search with advanced options
+
+  ```bash
+  # Basic CQL search
+  uv run --project vds_cli vds-cli confluence search --cql "type = page AND space = TTTC" --limit 25
+
+  # Advanced CQL search with excerpt and pagination
+  uv run --project vds_cli vds-cli confluence search --cql "type = page" --advanced --excerpt "highlighted" --start 10 --limit 50
+
+  # Advanced search with expand options
+  uv run --project vds_cli vds-cli confluence search --cql "title ~ 'test'" --advanced --expand "body.storage,space" --limit 25
+  ```
+
+  > **Note**: Use `--advanced` flag or `--excerpt` parameter to enable advanced search with additional options like
+  > excerpt strategies and expanded pagination.
+
+- **`search-by-space-type`** - Search by space and/or content type (helper that builds CQL automatically)
+
+  ```bash
+  # Search by space only
+  uv run --project vds_cli vds-cli confluence search-by-space-type --space TTTC --limit 50
+
+  # Search by content type only
+  uv run --project vds_cli vds-cli confluence search-by-space-type --type page --limit 25
+
+  # Search by both space and type
+  uv run --project vds_cli vds-cli confluence search-by-space-type --space TTTC --type page --start 0 --limit 50
+
+  # With expand options
+  uv run --project vds_cli vds-cli confluence search-by-space-type --space TTTC --type blogpost --expand "body.storage,version"
+  ```
+
+  > **Note**: At least one of `--space` or `--type` must be provided. This helper automatically builds the CQL query for
+  > you.
+
+### User & Group Management
+
+- **`group list`** - List all groups
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence group list --limit 50
+  uv run --project vds_cli vds-cli confluence group list --start 0 --limit 100
+  ```
+
+- **`group members`** - Get group members
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence group members --group "confluence-users"
+  uv run --project vds_cli vds-cli confluence group members --group "admins" --start 0 --limit 100
+  ```
+
+- **`user get`** - Get user details
+
+  ```bash
+  # By username
+  uv run --project vds_cli vds-cli confluence user get --username testuser
+  uv run --project vds_cli vds-cli confluence user get --username testuser --expand status,details
+
+  # By user key
+  uv run --project vds_cli vds-cli confluence user get --userkey key123
+  ```
+
+- **`user password`** - Change user password (requires confirmation)
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence user password \
+    --username testuser \
+    --new-password "newpass123" \
+    --yes
+  ```
+
+  > **Security Note**: Password changes require `--yes` flag for confirmation. Use strong passwords and follow security
+  > best practices.
+
+- **`user group-add`** - Add user to group (requires confirmation)
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence user group-add \
+    --username testuser \
+    --group "confluence-users" \
+    --yes
+  ```
+
+- **`user group-remove`** - Remove user from group (requires confirmation)
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence user group-remove \
+    --username testuser \
+    --group "confluence-users" \
+    --yes
+  ```
+
+### Export Operations
+
+- **`export page`** - Export page as PDF
+
+  ```bash
+  # Export to file
+  uv run --project vds_cli vds-cli confluence export page --page-id 99647801 --output page.pdf
+
+  # Export to stdout (binary)
+  uv run --project vds_cli vds-cli confluence export page --page-id 99647801 > page.pdf
+
+  # API version is auto-detected (Cloud vs Server based on URL)
+  uv run --project vds_cli vds-cli confluence export page --page-id 99647801 --output page.pdf
+  ```
+
+  > **Note**: API version is automatically detected based on server URL (Cloud vs Server). The `--api-version` flag is
+  > accepted for CLI compatibility but the SDK auto-detects the mode from client initialization.
+
+- **`export space`** - Get space export download URL
+
+  ```bash
+  # PDF export
+  uv run --project vds_cli vds-cli confluence export space --space-key TTTC --export-type pdf
+
+  # HTML export
+  uv run --project vds_cli vds-cli confluence export space --space-key TTTC --export-type html
+
+  # XML export
+  uv run --project vds_cli vds-cli confluence export space --space-key TTTC --export-type xml
+  ```
+
+  > **Note**: Export types supported: `pdf`, `html`, `xml`. The command returns a download URL that can be used to fetch
+  > the exported content.
+
+### Draft Management (Server-only)
+
+- **`draft get`** - Get draft page by ID
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence draft get --page-id 12345
+  ```
+
+  > **Note**: Server/Data Center only. Not available in Cloud.
+
+- **`draft list`** - List all draft pages in a space
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence draft list --space-key TTTC --limit 50
+  ```
+
+  > **Note**: Server/Data Center only. Returns draft pages that haven't been published.
+
+- **`draft remove`** - Remove a draft page
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence draft remove --page-id 12345 --yes
+  ```
+
+  > **Warning**: Server/Data Center only. Requires `--yes` flag for confirmation. This permanently removes the draft.
+
+### Advanced Content Operations
+
+- **`content ancestors`** - Get page ancestors (parent pages)
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence content ancestors 99647801
+  ```
+
+  > Returns the hierarchy of parent pages for a given page.
+
+- **`content move`** - Move page to a new location
+
+  ```bash
+  # Move page as child of target page
+  uv run --project vds_cli vds-cli confluence content move 99647801 \
+    --target-title "Parent Page" \
+    --position append \
+    --yes
+
+  # Move page before target page
+  uv run --project vds_cli vds-cli confluence content move 99647801 \
+    --target-title "Sibling Page" \
+    --position before \
+    --yes
+  ```
+
+  > **Notes**:
+  >
+  > - Requires `--yes` flag for confirmation
+  > - `--position` can be: `append` (as child), `before`, or `after` (as sibling)
+  > - `--target-title` is the title of the target page
+
+- **`content tables`** - Extract tables from page
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence content tables 99647801
+  ```
+
+  > Extracts all tables from the page content and returns structured table data.
+
+- **`content regex`** - Extract regex matches from page
+
+  ```bash
+  # Extract email addresses
+  uv run --project vds_cli vds-cli confluence content regex 99647801 \
+    --pattern "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"
+
+  # Extract version numbers
+  uv run --project vds_cli vds-cli confluence content regex 99647801 \
+    --pattern "v\d+\.\d+\.\d+"
+  ```
+
+  > **Note**: Uses Python regex syntax. Returns all matches found in the page content.
+
+- **`content restrictions`** - Get content restrictions
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence content restrictions 99647801
+  ```
+
+  > Returns all viewing/editing restrictions configured for the content.
+
+### History & Versioning
+
+- **`history get`** - Get page history
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence history get --page-id 99647801
+  ```
+
+  > Returns the complete version history of a page, including all versions and their metadata.
+
+- **`history version`** - Get specific version
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence history version --page-id 99647801 --version 2
+  ```
+
+  > Returns the content of a specific version of a page.
+
+- **`history remove`** - Remove history (experimental)
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence history remove --page-id 99647801 --version 2 --yes
+  ```
+
+  > **Warning**: Experimental feature. Requires `--yes` flag for confirmation. Permanently removes a specific version
+  > from the page history.
+
+### Cache Management (Server-only)
+
+- **`cache statistics`** - Get cache statistics
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence cache statistics
+  uv run --project vds_cli vds-cli confluence cache statistics --server external
+  ```
+
+  > **Note**: Server/Data Center only. Returns cache hit/miss statistics and performance metrics.
+
+- **`cache flush`** - Flush cache
+
+  ```bash
+  # Flush all caches
+  uv run --project vds_cli vds-cli confluence cache flush --yes
+
+  # Flush specific cache package
+  uv run --project vds_cli vds-cli confluence cache flush --cache-name "com.gliffy.cache.gon" --yes
+  ```
+
+  > **Warning**: Server/Data Center only. Requires `--yes` flag for confirmation. Flushes all caches or a specific cache
+  > package (e.g., `com.gliffy.cache.gon`).
+
+- **`cache size`** - Get cache size information
+
+  ```bash
+  uv run --project vds_cli vds-cli confluence cache size
+  uv run --project vds_cli vds-cli confluence cache size --server external
+  ```
+
+  > **Note**: Server/Data Center only. Returns total cache size and cache count information.
+
+### Space Permissions & Management
+
+- **`space-permissions`** - Manage space permissions (get, set, remove)
+- **`space-management`** - Manage space lifecycle (archive, trash-list, trash-remove)
+
+## Recently Added
+
+- ✅ Advanced Search Operations (advanced CQL search, search-by-space-type) - **NEW**
+- ✅ Cache Management (Server-only: cache statistics/flush/size) - **NEW**
+- ✅ History & Versioning (history get/version/remove) - **NEW**
+- ✅ Advanced Content Operations (ancestors, move, tables, regex, restrictions) - **NEW**
+- ✅ Draft Management (Server-only: draft get/list/remove) - **NEW**
+- ✅ Export Operations (page PDF export, space export URLs) - **NEW**
+- ✅ User & Group Management (group list/members, user get/password/group-add/group-remove) - **NEW**
+- ✅ Space Permissions Management - **NEW**
+- ✅ Space Management (archive, trash operations) - **NEW**
+
+## Pending Work (Phase 2+)
+
+- Pagination helpers + structured analytics exports
+- Final hand-off from bash modules once feature parity is reached

package/tools/vds-scripts/confluence_orchestrator/SYNC_SCRIPTS.md

@@ -0,0 +1,127 @@
+# Confluence Sync Scripts
+
+This directory contains standalone sync scripts for synchronizing local files with Confluence attachments.
+
+## Standard Practice: Use VDS CLI
+
+**✅ RECOMMENDED**: Use the unified VDS CLI to run sync commands:
+
+```bash
+# Sync PDFs to Confluence
+uv run --project vds_cli vds-cli confluence sync pdfs \
+  <page_id> \
+  --dir /path/to/pdf/directory \
+  --server external
+
+# Sync PNGs to Confluence
+uv run --project vds_cli vds-cli confluence sync pngs \
+  <page_id> \
+  --dir /path/to/png/directory \
+  --server external
+
+# Regenerate PDFs from markdown (via PDF orchestrator)
+uv run --project vds_cli vds-cli pdf -- md2pdf file.md -o file.pdf
+```
+
+## Standalone Script Execution
+
+If you need to run scripts directly (e.g., for automation or debugging), use:
+
+```bash
+cd /path/to/vds-scripts/confluence_orchestrator
+
+# Sync PDFs
+uv run --project confluence_orchestrator python sync_pdfs_to_confluence.py \
+  sync <page_id> --dir /path/to/pdfs --server external
+
+# Sync PNGs
+uv run --project confluence_orchestrator python sync_png_attachments.py \
+  sync <page_id> --dir /path/to/pngs --server external
+
+# Regenerate PDFs from markdown
+uv run --project confluence_orchestrator python sync_pdfs_from_markdown.py \
+  /path/to/target-state
+```
+
+## Scripts
+
+### `sync_pdfs_to_confluence.py`
+
+Syncs local PDF files with Confluence page attachments.
+
+**Commands**:
+- `list <page_id>` - List PDF attachments on a page
+- `sync <page_id> --dir <directory>` - Sync PDFs from directory to page
+
+**Options**:
+- `--server` - Confluence server (internal|external)
+- `--pattern` - Filter PDF files by pattern
+- `--dry-run` - Show what would be done without making changes
+- `--comment` - Comment for attachment updates
+- `--yes` - Auto-confirm without prompting
+
+### `sync_png_attachments.py`
+
+Syncs local PNG files with Confluence page attachments.
+
+**Commands**:
+- `list <page_id>` - List PNG attachments on a page
+- `sync <page_id> --dir <directory>` - Sync PNGs from directory to page
+
+**Options**: Same as `sync_pdfs_to_confluence.py`
+
+### `sync_pdfs_from_markdown.py`
+
+Regenerates PDF files from markdown sources using `vds-cli pdf md2pdf`.
+
+**Usage**:
+```bash
+uv run --project confluence_orchestrator python sync_pdfs_from_markdown.py \
+  /path/to/directory \
+  [--pattern "*.md"] \
+  [--dry-run]
+```
+
+**Options**:
+- `--pattern` - Filter markdown files by pattern (e.g., `"*-schema.md"`)
+- `--dry-run` - Show what would be regenerated without actually regenerating
+
+## Environment Requirements
+
+All scripts require:
+- `confluence_orchestrator` package installed (via `uv sync`)
+- Confluence credentials in the shared VDS env file:
+  - `INTERNAL_CONFLUENCE_TOKEN` or `EXTERNAL_CONFLUENCE_TOKEN`
+- For PDF generation: `vds_cli` package with PDF orchestrator
+
+## Integration with VDS CLI
+
+The sync commands are integrated into the unified VDS CLI:
+
+```bash
+# List PDF attachments
+uv run --project vds_cli vds-cli confluence content attachments \
+  --page <page_id> --server external
+
+# Sync PDFs (via sync command)
+uv run --project vds_cli vds-cli confluence sync pdfs \
+  <page_id> --dir /path/to/pdfs --server external
+```
+
+## Troubleshooting
+
+**ModuleNotFoundError: No module named 'confluence_orchestrator'**:
+- Ensure you're running from `vds-scripts/confluence_orchestrator` directory
+- Or use `uv run --project confluence_orchestrator python <script>`
+- Or use the unified CLI: `uv run --project vds_cli vds-cli confluence sync ...`
+
+**PDF generation fails**:
+- Ensure `vds_cli` package is installed: `uv sync --project vds_cli`
+- Check that `vds-cli pdf md2pdf` works independently
+
+**Confluence authentication fails**:
+- Run `uv run --project vds_cli vds-cli env load` to load credentials
+- Verify the shared VDS env file contains the required tokens
+
+ns
+

package/tools/vds-scripts/confluence_orchestrator/SYNC_STANDARDIZATION.md

@@ -0,0 +1,108 @@
+# Sync Scripts Standardization
+
+**Date**: 2025-12-15  
+**Status**: ✅ Complete
+
+## Summary
+
+Standardized PDF and PNG sync scripts to follow VDS CLI best practices. Sync scripts are now integrated into the unified VDS CLI and located in the `confluence_orchestrator` directory for consistency.
+
+## Changes Made
+
+### 1. Script Relocation
+
+- **Moved** `sync_pdfs_from_markdown.py` from `docs-nttc/projects/INSURANCE/analysis/target-state/architecture/scripts/` to `vds-scripts/confluence_orchestrator/`
+- **Moved** `sync_pdfs_to_confluence.py` from `docs-nttc/projects/INSURANCE/analysis/target-state/architecture/scripts/` to `vds-scripts/confluence_orchestrator/`
+- **Reason**: Consistency with existing `sync_png_attachments.py` location and VDS orchestrator structure
+
+### 2. CLI Integration
+
+- **Added** `sync` subcommand group to `confluence_orchestrator.cli`
+- **Added** `sync pdfs` command that delegates to `sync_pdfs_to_confluence.py`
+- **Added** `sync pngs` command that delegates to `sync_png_attachments.py`
+- **Accessible via**: `uv run --project vds_cli vds-cli confluence sync pdfs/pngs`
+
+### 3. Path Fixes
+
+- **Fixed** hardcoded absolute path in `sync_pdfs_from_markdown.py` to use relative path based on script location
+- **Updated** `VDS_SCRIPTS` path calculation to be relative: `Path(__file__).resolve().parent.parent`
+
+### 4. Documentation Updates
+
+- **Created** `SYNC_SCRIPTS.md` in `confluence_orchestrator/` with complete usage guide
+- **Updated** `confluence_orchestrator/README.md` with sync command examples
+- **Updated** `architecture/scripts/README.md` to note script relocation and point to new location
+- **Updated** `PDF_SYNC_WORKFLOW.md` to reflect standard practice (VDS CLI usage)
+
+## Standard Practice
+
+### ✅ Recommended: Use VDS CLI
+
+```bash
+# Sync PDFs to Confluence
+uv run --project vds_cli vds-cli confluence sync pdfs \
+  <page_id> \
+  --dir /path/to/pdf/directory \
+  --server external
+
+# Sync PNGs to Confluence
+uv run --project vds_cli vds-cli confluence sync pngs \
+  <page_id> \
+  --dir /path/to/png/directory \
+  --server external
+```
+
+### Alternative: Direct Script Execution
+
+```bash
+cd vds-scripts/confluence_orchestrator
+
+# Sync PDFs
+uv run --project confluence_orchestrator python sync_pdfs_to_confluence.py \
+  sync <page_id> --dir <directory> --server external
+
+# Sync PNGs
+uv run --project confluence_orchestrator python sync_png_attachments.py \
+  sync <page_id> --dir <directory> --server external
+
+# Regenerate PDFs from markdown
+uv run --project confluence_orchestrator python sync_pdfs_from_markdown.py \
+  /path/to/target-state --dry-run
+```
+
+## Testing
+
+✅ **Validated**:
+- `sync_pdfs_from_markdown.py` runs successfully from `confluence_orchestrator/` directory
+- Script correctly finds markdown files and generates sync plan
+- Path resolution works correctly with relative paths
+
+⚠️ **Note**: Full end-to-end testing requires:
+- Confluence credentials in the shared VDS env file
+- Access to Confluence server
+- PDF generation via `vds-cli pdf md2pdf`
+
+## Files Modified
+
+1. `vds-scripts/confluence_orchestrator/src/confluence_orchestrator/cli.py` - Added sync commands
+2. `vds-scripts/confluence_orchestrator/sync_pdfs_from_markdown.py` - Fixed path resolution
+3. `vds-scripts/confluence_orchestrator/sync_pdfs_to_confluence.py` - Copied from original location
+4. `vds-scripts/confluence_orchestrator/SYNC_SCRIPTS.md` - New documentation
+5. `vds-scripts/confluence_orchestrator/README.md` - Updated with sync examples
+6. `docs-nttc/projects/INSURANCE/analysis/target-state/architecture/scripts/README.md` - Updated to note relocation
+
+## Benefits
+
+1. **Consistency**: All sync scripts in one location (`confluence_orchestrator/`)
+2. **Unified CLI**: Access via `vds-cli confluence sync` commands
+3. **Standard Practice**: Follows VDS orchestrator patterns
+4. **Maintainability**: Single source of truth for sync functionality
+5. **Documentation**: Complete usage guide in `SYNC_SCRIPTS.md`
+
+## Next Steps
+
+- [ ] Test full end-to-end sync workflow (markdown → PDF → Confluence)
+- [ ] Add sync commands to main VDS CLI help documentation
+- [ ] Consider adding sync commands to other orchestrators if needed
+- [ ] Monitor usage and gather feedback for improvements
+