@ngocsangairvds/vsaf 4.1.17 → 4.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "4.1.17",
+  "version": "4.1.18",
   "description": "logging step",
   "main": "packages/core/dist/index.js",
   "types": "packages/core/dist/index.d.ts",

package/skills/vds-skill/vds-scripts-skill/SKILL.md

@@ -118,6 +118,7 @@ uv run --directory ~/.claude/vds-scripts --package spec_orchestrator vds-spec --
 
 When fetching or exporting Confluence page content (especially BRD, KBNV, SRS pages with tables and images), you **MUST** read and follow `references/confluence-content-export.md` before proceeding. Key rules:
 
+0. **Output to `.vsaf/docs/confluence/<page-title>/`** — never to `docs/` at project root
 1. **Use `body.storage`** (not `body.view`) as source of truth for image references
 2. **Only download attachments referenced in `body.storage`** — never bulk-download all attachments
 3. **Preserve image position** in output — replace `ac:image` with `![](images/...)` in-place, never collect at end

package/skills/vds-skill/vds-scripts-skill/references/confluence-content-export.md

@@ -2,6 +2,30 @@
 
 When extracting content from a Confluence page (BRD, KBNV, SRS, or any page with tables/images), follow these rules strictly. Violations cause data loss that is invisible to the user.
 
+## Rule 0 — Output Directory
+
+All Confluence export artifacts **MUST** be placed under `.vsaf/docs/` in the project root, **not** in `docs/` at root.
+
+```
+<project-root>/
+├── .vsaf/
+│   └── docs/
+│       └── confluence/
+│           ├── <page-title>/
+│           │   ├── content.md
+│           │   └── images/
+│           │       ├── screen-login.png
+│           │       └── flow-diagram.png
+│           └── <another-page>/
+│               ├── content.md
+│               └── images/
+└── docs/          ← project docs, NOT for Confluence exports
+```
+
+- Use `.vsaf/docs/confluence/<page-title>/` as the output directory for each page.
+- This keeps Confluence artifacts separate from project documentation and co-located with other VSAF working files.
+- Pass `--out .vsaf/docs/confluence/<page-title>/` when using CLI commands that accept output path.
+
 ## Rule 1 — Use `body.storage` as the Single Source of Truth for Image Refs
 
 - **Never** rely on `body.view` for image references — it is post-render HTML that may add or drop images via macros.
@@ -71,12 +95,14 @@ If the user requests "all attachments" (audit/backup scenario):
 - Report summary: `Used: N inline / Total: M attached`
 
 ```bash
-# Download only referenced attachments
+# Download only referenced attachments into .vsaf/docs/confluence/<page>/images/
+OUT_DIR=".vsaf/docs/confluence/<page-title>"
+mkdir -p "$OUT_DIR/images"
 for filename in $REFERENCED_FILES; do
   att_id=$(vds-cli confluence content list-attachments <PAGE_ID> --json-only \
     | jq -r ".[] | select(.title == \"$filename\") | .id")
   uv run --directory ~/.claude/vds-scripts --package vds-cli \
-    vds-cli confluence content download-attachment "$att_id" --out "images/$filename"
+    vds-cli confluence content download-attachment "$att_id" --out "$OUT_DIR/images/$filename"
 done
 ```
 
@@ -98,6 +124,10 @@ Do not report success if counts diverge.
 ## Rule 5 — Correct Invocation Sequence (Step by Step)
 
 ```bash
+# B0: Set output directory
+OUT_DIR=".vsaf/docs/confluence/<page-title>"
+mkdir -p "$OUT_DIR/images"
+
 # B1: Fetch storage body (source of truth for image refs)
 uv run --directory ~/.claude/vds-scripts --package vds-cli \
   vds-cli confluence content page <PAGE_ID> --expand body.storage
@@ -106,12 +136,12 @@ uv run --directory ~/.claude/vds-scripts --package vds-cli \
 
 # B3: Download only referenced attachments
 uv run --directory ~/.claude/vds-scripts --package vds-cli \
-  vds-cli confluence content download-attachment <ATT_ID> --out images/<filename>
+  vds-cli confluence content download-attachment <ATT_ID> --out "$OUT_DIR/images/<filename>"
 
 # B4: Convert storage XHTML → markdown (see Rule 2 Python snippet)
 #     - ac:image → ![](images/...) in-place
 #     - tables stay as HTML
-#     - output: content.md + images/
+#     - output: $OUT_DIR/content.md + $OUT_DIR/images/
 
 # B5: Verify (see Rule 4)
 ```
@@ -125,3 +155,4 @@ uv run --directory ~/.claude/vds-scripts --package vds-cli \
 | Flatten `<table>` to markdown `\|` pipe tables | Destroys merged cells, nested bullets, colspan/rowspan |
 | Collect images at end of document | Breaks image↔context mapping (which screen? which step?) |
 | Skip verification | Silent data loss — user trusts output without knowing images are missing |
+| Export to `docs/` at project root | Pollutes project docs; use `.vsaf/docs/confluence/` instead |