Clarify skill and intermediate artifact docs

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: oceanusXXD

README.md

@@ -45,6 +45,8 @@ Once that information is materialized as Skills, it can be consumed directly by
 
 It covers the full chain from repository scanning, structural analysis, Skill planning, and document generation to tool-specific rule adaptation. It also supports incremental regeneration so Skills can stay aligned as the repository evolves.
 
+In product terms, the final deliverable is the Skill layer itself. Generated Skills under `skills/` and the tool-specific files published by `adapt` are the end product. Blueprints, plans, reports, references, and state snapshots remain explicit intermediate artifacts that support review, debugging, and CI-safe refresh.
+
 For one-off local analysis, `code2skill` can scan an entire repository and generate the full result set.
 For ongoing development workflows, it can combine historical state and code diffs to rebuild only the affected Skills, reducing repeated generation cost and making CI-based updates practical.
 
@@ -94,13 +96,15 @@ This is not the final architecture destination, but it is a meaningful step upwa
 
 From one Python repository, `code2skill` can produce:
 
-- `project-summary.md` for a human-readable repository overview
-- `skill-blueprint.json` for the Phase 1 structural blueprint
-- `skill-plan.json` for the LLM-planned skill set
-- `skills/index.md` and `skills/*.md` for grounded AI-consumable skill documents
-- `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, `.github/copilot-instructions.md`, and `.windsurfrules` via `adapt`
-- `report.json` for execution metrics, token estimates, and impact summaries
-- `state/analysis-state.json` for incremental CI reuse
+- final Skill products
+  - `skills/index.md` and `skills/*.md` for grounded AI-consumable skill documents
+  - `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, `.github/copilot-instructions.md`, and `.windsurfrules` via `adapt`
+- intermediate artifacts
+  - `project-summary.md` for a human-readable repository overview
+  - `skill-blueprint.json` for the Phase 1 structural blueprint
+  - `skill-plan.json` for the LLM-planned skill set
+  - `report.json` for execution metrics, token estimates, and impact summaries
+  - `state/analysis-state.json` for incremental CI reuse
 
 ## The Role Of Skills In A Repository
 

README.zh-CN.md

@@ -45,6 +45,8 @@ Skill 可以表达例如以下信息：
 
 它覆盖从仓库扫描、结构分析、Skill 规划、文档生成到工具规则适配的完整链路，也支持增量重建，让 Skill 能随着仓库演进保持同步。
 
+从产品语义上说，最终交付物是 Skill 层本身。`skills/` 下生成的 Skill 文档，以及通过 `adapt` 发布到目标工具位置的规则文件，才是最终产物；blueprint、plan、report、references、state 则是支撑审阅、调试和 CI 增量刷新的中间工件。
+
 对于一次性的本地分析，`code2skill` 可以扫描整个仓库并生成完整结果。对于持续开发场景，它可以结合历史 state 和代码 diff，只重建受影响的 Skill，降低重复生成成本，让 CI 内自动更新成为可行方案。
 
 ## 它保证什么
@@ -93,13 +95,15 @@ Skill 可以表达例如以下信息：
 
 针对一个 Python 仓库，`code2skill` 可以产出：
 
-- `project-summary.md`：面向人的仓库概览
-- `skill-blueprint.json`：Phase 1 的结构蓝图
-- `skill-plan.json`：LLM 规划出的 Skill 列表
-- `skills/index.md` 和 `skills/*.md`：供 AI 直接消费的 Skill 文档
-- 通过 `adapt` 生成 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules/*`、`.github/copilot-instructions.md`、`.windsurfrules`
-- `report.json`：执行指标、token 估算和影响摘要
-- `state/analysis-state.json`：供增量 CI 复用的状态快照
+- 最终 Skill 产物
+  - `skills/index.md` 和 `skills/*.md`：供 AI 直接消费的 Skill 文档
+  - 通过 `adapt` 生成 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules/*`、`.github/copilot-instructions.md`、`.windsurfrules`
+- 中间工件
+  - `project-summary.md`：面向人的仓库概览
+  - `skill-blueprint.json`：Phase 1 的结构蓝图
+  - `skill-plan.json`：LLM 规划出的 Skill 列表
+  - `report.json`：执行指标、token 估算和影响摘要
+  - `state/analysis-state.json`：供增量 CI 复用的状态快照
 
 ## Skill 在仓库中的角色
 

docs/output-layout.md

@@ -4,6 +4,8 @@ By default, `code2skill` writes artifacts under `.code2skill/` inside the target
 
 This directory is the default artifact bundle root for the repository workflow. It groups the structural analysis outputs, planning outputs, generated Skills, diagnostics, and incremental state under one predictable location.
 
+Within this bundle, `code2skill` treats generated Skills as the final product layer. The other files remain important, but they are intermediate artifacts that support generation, review, reporting, and incremental CI refresh.
+
 ```text
 .code2skill/
   project-summary.md
@@ -24,14 +26,20 @@ This directory is the default artifact bundle root for the repository workflow.
 
 ## Artifact Roles
 
+### Final product artifacts
+
+- `skills/index.md` and `skills/*.md`: grounded AI-consumable Skill documents
+
+### Intermediate artifacts
+
 - `project-summary.md`: human-readable project overview
 - `skill-blueprint.json`: structural analysis output from Phase 1
 - `skill-plan.json`: LLM-planned Skill inventory
-- `skills/index.md` and `skills/*.md`: grounded AI-consumable Skill documents
 - `report.json`: execution metrics, cost estimates, and impact summaries
+- `references/*.md`: supporting architectural and workflow references
 - `state/analysis-state.json`: incremental execution cache
 
-In product terms, `.code2skill/` is the workspace-local artifact bundle, while `adapt` writes the final target-facing instruction files into the repository locations where each AI tool expects them.
+In product terms, `.code2skill/` is the workspace-local artifact bundle. The final repository-local product is the generated Skill set, while `adapt` publishes that Skill layer into the repository locations where each AI tool expects to read it.
 
 ## Adapted Outputs
 

docs/python-api.md

@@ -76,6 +76,11 @@ The pipeline functions return `ScanExecution`, which includes:
 - `report_path`
 - `report`
 
+The embedded `ExecutionReport` also distinguishes between:
+
+- `final_product_files`: the generated Skill artifacts inside the bundle
+- `intermediate_artifact_files`: blueprint, plan, references, report, and state-side artifacts that support the workflow
+
 The lower-level config and report dataclasses are also exported from the package root. The package root also exports the new artifact and summary contracts used by the workflow-oriented surface:
 
 ```python