create-yss-spec 3.4.7 → 3.4.9

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/SKILL.md

@@ -5,16 +5,16 @@ description: "Narrow conversion skill. Invoke only when the user explicitly asks
 
 # Report To Google Doc
 
-Use this skill only when the user explicitly needs a shareable Google Drive document from an existing HTML analytics report. The source must be an HTML report: a local file, a downloaded blob-hosted report, or a report produced by `$build-report`
+Use this skill when the user requests a local DOCX, a hosted DOCX, or a native Google Doc from an existing HTML analytics report. The source must be an HTML report: a local file, a downloaded blob-hosted report, or a report produced by `$build-report`
 HTML mode. This skill does not convert a live MCP app report directly.
 
-The expected path is HTML -> DOCX -> Drive upload. It is acceptable for Drive to host the upload as a DOCX-backed viewer file rather than a native Google Docs MIME type. Do not use the old Google Docs batch-update request path.
+Choose the requested target: `local-docx` (default for local conversion), `hosted-docx`, or `native-google-docs`. HTML → DOCX is local work; uploading is a separate external action, performed only when requested. A hosted DOCX viewer is not a native Google Doc. Discover an available conversion/import capability and verify the result MIME/type before claiming native delivery.
 
 ## Skill Configuration
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 
@@ -30,6 +30,8 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
      --out-dir /tmp/report_to_google_doc_plan
    ```
 
+   The helper defaults to `--target local-docx`. Only for an explicit cloud request, select `--target hosted-docx` or `--target native-google-docs`; the helper still performs no remote action. If dependencies are unavailable and cannot be installed in the authorized scope, use an available local converter and validate against the source, or report the conversion gap.
+
    Omit `--render-workers` on the normal path. Only pass a worker count after benchmarking the same report family locally. If dependencies are missing,
    use a local virtual environment with `beautifulsoup4`, `pillow`, and `python-docx`; `cairosvg` or headless Playwright are optional renderers.
 
@@ -42,32 +44,20 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
      and rendered visual inventory
    - `preflight_checks.json`: source, width, DOCX, and rendered-image checks
    - `report.docx`: generated local Word document
-   - `docx_upload_plan.json`: compact upload instructions
+   - `docx_upload_plan.json`: selected-target handoff plan (no upload steps for local conversion)
    - `placeholder_queries.json`: source mapping debug labels
 
    Do not upload until `preflight_checks.json` has `status: "passed"` with zero errors. Warnings must either be fixed or called out in the handoff.
 
-4. Upload the DOCX.
-
-   ```json
-   mcp__codex_apps__google_drive._upload_file({
-     "file_uri": "/tmp/report_to_google_doc_plan/report.docx",
-     "file_name": "Report Name.docx",
-     "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
-   })
-   ```
-
-   Treat the returned Drive URL as the deliverable. Do not attempt to force native Google Docs conversion, and do not fall back to `_batch_update_document`.
+4. Complete the selected target.
 
-5. Validate the uploaded result.
+   For `local-docx`, validate the local DOCX against the source inventory and stop with its local link. Do not upload, change sharing, or require a Drive connector.
 
-   Confirm the uploaded file is readable and non-empty. Compare uploaded text against the source inventory: title, section headings, executive summary or answer callout, caveats, recommendations, source notes, and source links.
-   Inspect the local `report.docx` structure when available: heading counts,
-   lists, tables, hyperlink relationships, and image relationships should match `manifest.json`.
+   For explicitly requested `hosted-docx` or `native-google-docs`, discover the currently available upload/import capability and read its schema. Never guess a tool name, plugin ID or parameter. If missing, deliver the validated local DOCX and identify the cloud capability gap; do not claim cloud completion or switch the target silently.
 
-6. Hand off the link.
+5. Verify and hand off.
 
-   Return the Drive/Docs URL, local DOCX path, source HTML path, and validation performed. Connector success alone is not enough; the handoff is complete only after the uploaded file and local DOCX structure have been checked against the source report.
+   Check headings, lists, tables, text, links and image relationships against `manifest.json`. For a cloud target, also reopen the returned document and verify content and actual native/hosted type. Return only the selected deliverable links plus source and validation evidence as useful. Connector success alone is insufficient.
 
 ## Standards
 
@@ -114,5 +104,5 @@ python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
 jq '.status, .summary' /tmp/report_to_google_doc_plan_smoke/preflight_checks.json
 test -f /tmp/report_to_google_doc_plan_smoke/report.docx
 test -f /tmp/report_to_google_doc_plan_smoke/docx_upload_plan.json
-git diff --check -- plugins/data-analytics/skills/build-report/report-to-google-doc
+git diff --check -- .codex/skills/data-analytics/skills/build-report/report-to-google-doc
 ```

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/scripts/report_to_google_doc/cli.py

@@ -1,14 +1,7 @@
-"""Build DOCX upload plans for sanitized HTML reports.
+"""Convert HTML to local DOCX and record the requested delivery target.
 
-The script intentionally does not call Google APIs. It produces deterministic
-artifacts that an agent can feed to the Google Drive connector:
-
-1. report.docx contains the locally converted report for Drive upload.
-2. docx_upload_plan.json gives the compact Google Drive upload sequence.
-3. manifest.json records the source inventory for verification.
-
-The expected deliverable is the uploaded DOCX-backed Drive file. Native Google
-Docs MIME conversion is not required.
+No Google APIs are called. Local delivery is the default. Cloud planning requires
+an explicit target and never substitutes for capability discovery or authorization.
 """
 
 from __future__ import annotations
@@ -47,6 +40,7 @@ def main() -> None:
         action="store_true",
         help="Write preflight_checks.json but do not fail the command when checks fail.",
     )
+    parser.add_argument("--target", choices=["local-docx", "hosted-docx", "native-google-docs"], default="local-docx")
     args = parser.parse_args()
     write_outputs(
         args.html,
@@ -54,4 +48,5 @@ def main() -> None:
         chart_mode=args.chart_mode,
         render_workers=args.render_workers,
         strict_preflight=not args.no_strict_preflight,
+        target=args.target,
     )

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/scripts/report_to_google_doc/plan.py

@@ -5,41 +5,45 @@ from pathlib import Path
 from typing import Any
 
 from .constants import DEFAULT_RENDER_WORKERS, DOC_CONTENT_WIDTH_PT
-from .docx_writer import write_docx
-from .html_parser import parse_html
-from .quality import build_preflight_checks
-from .rendering import render_chart_images
 
 
 def build_docx_upload_plan(
     manifest: dict[str, Any],
     docx_path: Path,
     preflight: dict[str, Any],
+    target: str = "local-docx",
 ) -> dict[str, Any]:
+    if target not in {"local-docx", "hosted-docx", "native-google-docs"}:
+        raise ValueError(f"Unsupported delivery target: {target}")
+    cloud = target != "local-docx"
+    sequence = []
+    if cloud and preflight["status"] == "passed":
+        sequence = [{
+            "capability": "upload_file" if target == "hosted-docx" else "import_native_google_document",
+            "discovery_required": True,
+            "requires_explicit_user_request": True,
+            "file": str(docx_path),
+            "note": "Discover the actual tool schema; capability names are not callable tools.",
+        }]
     return {
         "title": manifest["title"],
         "source_html": manifest["source_html"],
         "docx_file": str(docx_path),
         "preflight_status": preflight["status"],
         "doc_content_width_pt": DOC_CONTENT_WIDTH_PT,
-        "sequence": [
-            {
-                "tool": "mcp__codex_apps__google_drive._upload_file",
-                "file_uri": str(docx_path),
-                "file_name": docx_path.name,
-                "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-            }
-        ],
-        "expected_drive_result": (
-            "A Drive-hosted DOCX file is acceptable. The file does not need to be "
-            "converted to the native Google Docs MIME type."
-        ),
+        "target": target,
+        "remote_action_performed": False,
+        "sequence": sequence,
+        "expected_result": {
+            "local-docx": "Validated local DOCX; no upload or sharing change.",
+            "hosted-docx": "Readable hosted DOCX; not a native Google Doc.",
+            "native-google-docs": "Reopened native Google Doc; a hosted DOCX does not satisfy this target.",
+        }[target],
         "verification": [
-            "fetch or open the uploaded Drive file and confirm it is readable",
-            "compare extracted text against manifest.json headings, lists, source notes, and links",
-            "inspect local report.docx structure for expected headings, tables, lists, and image relationships",
-            "compare generated chart_images/*.png against the HTML report visuals when visual fidelity matters",
-        ],
+            "compare text and structure against manifest.json and source HTML",
+            "inspect headings, tables, lists, links and image relationships",
+            "compare rendered charts with source visuals when applicable",
+        ] + (["reopen the cloud result and verify content and actual native/hosted type"] if cloud else []),
     }
 
 
@@ -52,38 +56,24 @@ def write_docx_upload_readme(
     manifest: dict[str, Any],
     preflight: dict[str, Any],
     docx_path: Path,
+    target: str = "local-docx",
 ) -> str:
-    return f"""# Report-to-Google-Doc DOCX Upload Plan
+    plan = build_docx_upload_plan(manifest, docx_path, preflight, target)
+    return f"""# HTML report delivery plan
 
 Source: `{html}`
-
 Local DOCX: `{docx_path}`
-
-Inventory:
-- headings: {manifest["counts"]["headings"]}
-- native tables/cards: {manifest["counts"]["tables"]}
-- chart images: {manifest["counts"].get("chart_images", 0)}
-- source two-column blocks: {manifest["counts"].get("two_col_source_blocks", 0)}
-- rendered two-column blocks: {manifest["counts"].get("two_col_image_blocks", 0)}
-- inline style spans: {manifest["counts"]["inline_styles"]}
-- lists: {manifest["counts"]["lists"]}
-- preflight: {preflight["status"]} ({preflight["summary"]["errors"]} errors,
-  {preflight["summary"]["warnings"]} warnings)
-
-Expected connector sequence:
-
-1. Inspect `preflight_checks.json`. Do not upload until preflight passes.
-2. Upload `{docx_path}` with `mcp__codex_apps__google_drive._upload_file`.
-3. Treat the Drive-hosted DOCX as the deliverable; it does not need native
-   Google Docs MIME conversion.
-4. Fetch/open the uploaded file and compare it against `manifest.json` and the
-   source HTML report.
-
-This helper intentionally writes only DOCX-upload artifacts. It does not write
-Google Docs batch-update request files such as `seed_requests.json`,
-`table_requests.json`, `content_replacement_requests_template.json`,
-`chart_image_requests_template.json`, `remote_write_plan.json`, or
-`all_requests*.json`.
+Target: `{target}`
+Preflight: `{preflight["status"]}`
+Expected result: {plan["expected_result"]}
+
+Check the source inventory in `manifest.json` and `preflight_checks.json`.
+For local-docx, validate and return the local file. Do not upload.
+A cloud target requires an explicit user request, passed preflight, actual tool
+capability discovery, and content/type verification after reopening the result.
+Missing capability is a delivery gap; a local file is not proof of cloud completion.
+This helper performs no remote actions. `docx_upload_plan.json` is a planning
+artifact with conditional capabilities, not executable tool instructions.
 """
 
 
@@ -93,7 +83,13 @@ def write_outputs(
     chart_mode: str = "image",
     render_workers: int = DEFAULT_RENDER_WORKERS,
     strict_preflight: bool = True,
+    target: str = "local-docx",
 ) -> None:
+    from .docx_writer import write_docx
+    from .html_parser import parse_html
+    from .quality import build_preflight_checks
+    from .rendering import render_chart_images
+
     out_dir.mkdir(parents=True, exist_ok=True)
     manifest = parse_html(html, chart_mode=chart_mode)
     if manifest.get("chart_images"):
@@ -113,6 +109,7 @@ def write_outputs(
         manifest,
         docx_path,
         preflight,
+        target,
     )
     write_json(out_dir / "docx_upload_plan.json", docx_upload_plan)
     readme = write_docx_upload_readme(
@@ -120,6 +117,7 @@ def write_outputs(
         manifest,
         preflight,
         docx_path,
+        target,
     )
     (out_dir / "README.md").write_text(readme, encoding="utf-8")
     if strict_preflight and preflight["status"] != "passed":

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/tests/test_delivery_plan.py

@@ -0,0 +1,45 @@
+"""External-action boundaries of the generated delivery plan, without cloud writes."""
+import sys
+from pathlib import Path
+import unittest
+
+sys.path.insert(0, str(Path(__file__).parents[1] / 'scripts'))
+from report_to_google_doc.plan import build_docx_upload_plan, write_docx_upload_readme
+
+
+class DeliveryPlanTests(unittest.TestCase):
+    def plan(self, target='local-docx', status='passed'):
+        return build_docx_upload_plan({'title': '报告', 'source_html': 'report.html'}, Path('report.docx'), {'status': status}, target)
+
+    def test_local_conversion_has_no_remote_sequence(self):
+        plan = self.plan()
+        self.assertEqual(plan['sequence'], [])
+        self.assertFalse(plan['remote_action_performed'])
+        self.assertEqual(plan['target'], 'local-docx')
+
+    def test_cloud_plans_require_discovery_and_explicit_request(self):
+        for target in ['hosted-docx', 'native-google-docs']:
+            plan = self.plan(target)
+            step = plan['sequence'][0]
+            self.assertNotIn('tool', step)
+            self.assertTrue(step['discovery_required'])
+            self.assertTrue(step['requires_explicit_user_request'])
+            self.assertFalse(plan['remote_action_performed'])
+        self.assertNotEqual(self.plan('hosted-docx')['sequence'][0]['capability'], self.plan('native-google-docs')['sequence'][0]['capability'])
+
+    def test_failed_validation_never_emits_cloud_steps(self):
+        for target in ['hosted-docx', 'native-google-docs']:
+            self.assertEqual(self.plan(target, 'failed')['sequence'], [])
+
+    def test_unknown_target_is_rejected(self):
+        with self.assertRaises(ValueError): self.plan('share-everywhere')
+
+    def test_readme_keeps_native_and_hosted_results_distinct(self):
+        readme = write_docx_upload_readme(Path('report.html'), {'title': '报告', 'source_html': 'report.html'}, {'status': 'passed'}, Path('report.docx'), 'native-google-docs')
+        self.assertIn('hosted DOCX does not satisfy', readme)
+        self.assertIn('performs no remote actions', readme)
+        self.assertNotIn('mcp__', readme)
+
+
+if __name__ == '__main__':
+    unittest.main()

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-slides/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: report-to-google-slides
-description: "Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing HTML analytics report into a native Google Slides deck."
+description: "Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing HTML analytics report into a local PPTX or native Google Slides deck."
 ---
 
 # Report To Google Slides
 
-Use this skill only when the user explicitly has an existing HTML analytics report and wants a Google Slides deliverable. The output should be a deck, not a pasted report. A stakeholder skimming the slides should understand the answer, evidence,
+Use this skill only when the user explicitly has an existing HTML analytics report and wants a local PPTX or native Google Slides deliverable. The output should be a deck, not a pasted report. A stakeholder skimming the slides should understand the answer, evidence,
 caveats, and recommended follow-up without opening the source report.
 
 This skill consumes an HTML report. It does not convert a live MCP app report directly; if only an MCP app report exists, build an HTML report from the same source evidence as a separate report delivery mode first.
@@ -14,7 +14,7 @@ This skill consumes an HTML report. It does not convert a live MCP app report di
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 
@@ -46,8 +46,7 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
 
 4. Import and verify in Google Slides.
 
-   Import `deck.pptx` with `mcp__codex_apps__google_drive._import_presentation` using `upload_mode="native_google_slides"`. Verify the imported deck with `_get_presentation_outline` and `_get_slide_thumbnail` for every slide when possible. At minimum, inspect the cover, one chart slide, one table slide,
-   and the caveats/sources slides.
+   For a local PPTX request, validate and hand off `deck.pptx` without upload. For an explicitly requested native Slides deliverable, discover the installed presentation import/readback capabilities and their schemas; do not assume tool names. Verify the imported native type, outline and rendered slides through available readback tools. Missing import/readback capability is a named gap; the local PPTX remains a separate deliverable, not proof of native completion.
 
 5. Repair before handoff.
 

package/template/.codex/skills/data-analytics/skills/build-report/report-to-pdf/SKILL.md

@@ -13,7 +13,7 @@ The expected path is static HTML -> Chrome headless print-to-PDF -> PDF verifica
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 

package/template/.codex/skills/data-analytics/skills/build-report/specifications/mcp-app-report.md

@@ -55,5 +55,5 @@ Before creating or revising an MCP app report artifact, read `../../../src/analy
 - Preserve the current manifest, bounded snapshot, inline-safe source text, package metadata, reading order, visuals, tables, source details, and narrative.
 - Keep static HTML and PDF exports content-only: include the report title, narrative, visuals, tables, and source details, but omit the interactive top bar and app-only controls.
 - Use the `sites-hosting` workflow for project resolution, local validation, source provenance, artifact preparation, version creation, deployment polling, and access control.
-- Default new hosted report access to `workspace_all` unless the user explicitly requests narrower access. Report the production URL and the configured access mode.
+- Use only the explicitly selected hosting audience; missing audience does not authorize workspace-wide access. Report the production URL and the configured access mode.
 - If the local report package files or validated artifact payload are unavailable, stop and ask for the missing source instead of publishing an empty, fallback, or stale report.

package/template/.codex/skills/data-analytics/skills/design-kpis/SKILL.md

@@ -11,7 +11,7 @@ Design KPI frameworks, set targets, and develop measurement plans that help team
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 

package/template/.codex/skills/data-analytics/skills/gather-business-context/SKILL.md

@@ -11,7 +11,7 @@ Use this skill to collect the business context needed to understand an analytica
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 

package/template/.codex/skills/data-analytics/skills/index/SKILL.md

@@ -11,7 +11,7 @@ Route broad Data Analytics requests to the right focused workflow. Treat invocat
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 
@@ -63,7 +63,7 @@ Use `inline` for bounded factual or computational answers that can be delivered
 
 Treat short quantitative prompts as Data Analytics work when answering them requires explaining how numbers compare, break down, concentrate, or move across multiple values, groups, or time points. Keep these routes lightweight by default: use `inline` for bounded answers and escalate to `report` only when the user asks for explanation, diagnosis, recommendation, or a durable artifact.
 
-Use `report` for explanation, diagnosis, decomposition, synthesis, recommendation, or larger analytical answers whose value materially improves from a durable artifact. When the user asks to interpret analytical source material or reviewed results, choose report mode when the answer needs evidence-backed narrative, caveats, source metadata, or a reader-facing artifact. $product-business-analysis, $metric-diagnostics, and $kpi-reporting imply `report`; every `report` route includes $build-report unless the user explicitly waives file or report creation.
+Use `report` for explanation, diagnosis, decomposition, synthesis, recommendation, or larger analytical answers whose value materially improves from a durable artifact. When the user asks to interpret analytical source material or reviewed results, choose report mode when the answer needs evidence-backed narrative, caveats, source metadata, or a reader-facing artifact. The focused skill name does not determine delivery mode. Preserve the user-selected `inline`, `report`, `local` file or `native` cloud target. A bounded KPI/diagnostic answer can remain inline; use $build-report only for a selected report deliverable. Cloud upload/sharing requires the corresponding user request and available capability.
 
 After choosing `inline` or `report`, use `$visualize-data` when a visual would make the result easier to understand, especially for category comparisons, part-to-whole breakdowns, rankings, movement over time, or more than a handful of comparable values, rows, categories, or time points. Prefer a visual pass over a scan-heavy table, and let `$visualize-data` choose the form, decide whether to render a chart, and align any table or prose to the visual takeaway.
 
@@ -79,7 +79,7 @@ After choosing `inline` or `report`, use `$visualize-data` when a visual would m
 
 If several focused skills apply, sequence them in the order that creates the most useful analyst workflow. For example, metric diagnostics may precede KPI reporting, semantic-layer setup may precede dashboard or report work, and product-business analysis may feed a recommendation-ready report. Keep this index as a router; do not perform focused workflow logic here.
 
-Before finalizing future Data Analytics instruction edits, run `python3 plugins/data-analytics/skills/user-context/scripts/validate_user_context_preflight.py` from the repository root. Treat a missing mandatory pre-answer gate in any `SKILL.md`, including helper skills, as an audit finding to fix before release.
+Before finalizing future Data Analytics instruction edits, run `python3 .codex/skills/data-analytics/skills/user-context/scripts/validate_user_context_preflight.py .codex/skills/data-analytics` from the repository root. Treat a missing mandatory pre-answer gate in any `SKILL.md`, including helper skills, as an audit finding to fix before release.
 
 Prefer examples that route to focused skills without extra setup, such as:
 
@@ -216,7 +216,7 @@ Use $build-report to build exactly one durable report surface selected for the u
 
 ### report-to-google-doc
 
-Use $report-to-google-doc to convert an existing local HTML report into a polished native Google Doc.
+Use $report-to-google-doc for HTML → local DOCX. Hosted DOCX and native Google Docs are separate optional targets: discover capabilities, preserve user intent, and verify the actual result type before claiming a native document.
 
 ### report-to-google-slides
 

package/template/.codex/skills/data-analytics/skills/jupyter-notebooks/SKILL.md

@@ -11,7 +11,7 @@ Create clean, reproducible Jupyter notebooks that are easy to skim, rerun, and h
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 

package/template/.codex/skills/data-analytics/skills/kpi-reporting/SKILL.md

@@ -17,7 +17,7 @@ Use $metric-diagnostics when the readout needs fresh driver investigation, then
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 
@@ -97,7 +97,7 @@ After the analysis is assembled and before shaping the final readout, use $valid
 
 ### 9. Shape The Readout
 
-Use the output shape the user requested. If they did not specify one, ask what format they want before building the readout. Common shapes include an inline written update, a document or report, a slide, or a slide deck.
+Use the output shape the user requested. If unspecified, use inline for a bounded readout and infer a durable format only when the task requires it; ask only when the delivery choice materially changes the requested work. Common shapes include an inline written update, a document or report, a slide, or a slide deck.
 
 After the format is selected, load `references/report-templates.md` and use the matching pattern as a starting point. Adapt it to the audience, evidence, and artifact.
 

package/template/.codex/skills/data-analytics/skills/market-sizing/SKILL.md

@@ -11,7 +11,7 @@ Use this skill to produce a defensible estimate of a market or opportunity from
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 

package/template/.codex/skills/data-analytics/skills/metric-diagnostics/SKILL.md

@@ -13,7 +13,7 @@ Clarify with the user when a missing input would materially change the analytica
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 

package/template/.codex/skills/data-analytics/skills/product-business-analysis/SKILL.md

@@ -11,7 +11,7 @@ Use this skill to answer product or business questions with data-backed evidence
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 

package/template/.codex/skills/data-analytics/skills/spreadsheets/SKILL.md

@@ -17,17 +17,17 @@ Read `charts.md` when creating or editing substantive charts, dashboards, or cha
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Google Sheets-targeted output
 
 ### New Creations
 
-For a net-new Google Sheets request, create and verify a local `.xlsx` with this skill first. The native Google Sheets deliverable must then be produced by the Google Drive plugin's spreadsheet import action, `mcp__codex_apps__google_drive_import_spreadsheet`, with `upload_mode: "native_google_sheets"`.
+For a net-new Google Sheets request, create and verify a local `.xlsx` with this skill first. For a requested native Google Sheets target, discover a currently available spreadsheet-import capability, read its actual schema, then import and verify the native result. Do not assume a callable name or upload-mode parameter.
 
 Do not use Computer Use, Browser Use, blank-Google-Sheets creation plus Google Sheets write APIs, or another direct-to-Sheets construction path for net-new Google Sheets unless the user explicitly asks for that alternate workflow. If they do, mention first that output quality is expected to be best when a local `.xlsx` is imported through the Google Drive plugin.
 
-If the Google Drive plugin is unavailable, use the plugin-install/user-elicitation flow to ask the user to install `google-drive@openai-curated`. If the plugin is available but `_import_spreadsheet` is missing, ask the user to reinstall or refresh the Google Drive plugin before continuing with the native Google Sheets deliverable.
+If the required cloud capability is unavailable, explain the gap and offer a verified local XLSX. Consult the host tool catalog and its installation policy before suggesting an exact plugin; never invent an ID or demand reinstall as the default repair.
 
 After successful native import, the user-facing deliverable is the Google Sheets link. Treat the local `.xlsx` as a build artifact unless the user explicitly asks to keep or receive it.
 
@@ -45,7 +45,7 @@ Use the Google Drive plugin's Google Sheets skill for edits to existing Google S
 - Prefer one executable `.mjs` builder; patch and rerun it when iterating. Do NOT use shell heredocs or keep extra builder copies.
 - If workspace dependencies or `@oai/artifact-tool` are unavailable, report a setup blocker; do not guess paths, install packages, use system deps, alter module resolution, copy/import bundled internals, or do a broad file system search.
 - Do not search package internals or dump prototypes to discover APIs. Use the API reference below; if blocked, run at most one exact `workbook.help("<api_or_feature>")` query before building.
-- Final response: include a short user-visible summary and standalone Markdown link(s) only to final `.xlsx` artifact(s), one per line: `[Revenue Model - MNST.xlsx](/absolute/path/to/revenue_model_mnst.xlsx)`.
+- Final response: include a short user-visible summary and standalone Markdown link(s) to the selected final deliverable: local `.xlsx` artifacts or verified native Google Sheets URLs, one per line: `[Revenue Model - MNST.xlsx](/absolute/path/to/revenue_model_mnst.xlsx)`.
 - Do not mention internal tooling or support artifacts such as builders, rendered previews, JSON/CSV/log files, or scratch files unless explicitly requested.
 - Do not use alternate workbook creation/editing libraries such as `openpyxl`, `xlsxwriter`, or `pandas.ExcelWriter` unless the user explicitly asks for a non-artifact-tool fallback.
 - For analysis outside workbook authoring, use JS or spreadsheet formulas when sufficient. If Python is needed, use bundled Python libraries, save JSON/CSV intermediates, and have the JS builder create the workbook. Keep auditable/user-editable calculations as formulas.