@captain_z/zsk 1.8.4 → 1.8.6

package/templates/project-init/.zsk/config.yaml

@@ -12,40 +12,48 @@ template:
 mode: standard
 scale: auto
 
-# Prepare source capture strategy:
-# - Register source origins under sources.prepare.<lane>.<source-id>.
-# - Prefer stable local exports or provider API/export URLs over bare browser
-#   pages when fidelity matters.
-# - Keep credentials out of config; reference env names under origin.auth or use
-#   .zsk/playwright/.auth storageState created by `zsk prepare auth`.
-# - Run `zsk prepare plan` before acquisition, `zsk prepare auth-check` for
-#   remote/private URLs, then `zsk prepare sync --source=<id> --allow-network`
-#   when acquisition is intentionally allowed.
-# - Design/Figma sources are evidence only. Pair them with
-#   .zsk/raws/prepare/ux/{topic}/interaction-handoff.md for page/module
-#   interaction details before proposal/spec/design consume them. In
-#   module-targeted preproposal runs, {topic} defaults to the module id.
-sources: {}
+# Provider connection profiles. Configure each platform once. Keep credentials
+# out of this file; reference environment variables or global profiles instead.
+providers: {}
+
+# Durable entry sources to prepare. Prefer one authority-bearing entry per
+# platform/domain, then let `zsk prepare draft|plan` discover child pages, files,
+# nodes, or issues into .zsk/evidence/prepare/*/config-draft.yaml and
+# source-promotion-suggestions.md. Do not hand-maintain every discovered child
+# in this file.
+resources: []
+
+# Routes map prepared resources into controlled consumption surfaces such as
+# .zsk/modules/<module>/_issues or module source references.
+routes: []
 
-# Example source shape:
-# sources:
-#   prepare:
-#     product:
-#       prd:
-#         type: prd
-#         origin:
-#           kind: local
-#           path: docs/PRD.md
-#         snapshot: .zsk/raws/prepare/product/prd.md
-#     design:
-#       figma-product:
-#         type: design-source
-#         origin:
-#           kind: url
-#           provider: figma
-#           url: https://www.figma.com/file/<file-id>/<name>
-#           exportPath: exports/figma-product.json
-#         snapshot: .zsk/raws/prepare/design/figma-product/source.md
+modules:
+  root: .zsk/modules
+  index: .zsk/modules/index.md
+  registry: []
+
+# Demo login bootstrap. Keep real credentials in local env files; put only env
+# key names here, then run `zsk demo auth -m <module>` once to save storageState.
+# automation:
+#   demo:
+#     auth:
+#       required: true
+#       loginUrl: http://localhost:3000/login
+#       storageState: .zsk/modules/{module}/_playwright/.auth/user.json
+#       envFiles:
+#         - ~/.zshrc
+#       env:
+#         username: DEMO_USERNAME
+#         password: DEMO_PASSWORD
+#       selectors:
+#         username: input[name="username"]
+#         password: input[type="password"]
+#         submit: button[type="submit"]
+
+# Current prepare implementation compatibility tree. Use it for durable
+# grouped prepare entries only. Auto-discovered children should stay in
+# evidence/raw indexes until a human promotes them from config-draft.yaml.
+sources: {}
 
 customize:
   roles: .zsk/roles.yaml

package/templates/project-init/.zsk/docs/CONFIG-SCHEMA.md

@@ -0,0 +1,131 @@
+# Config Schema
+
+`.zsk/config.yaml` is the project control surface. It should describe intent,
+not runtime results.
+
+## Top-Level Blocks
+
+| Block | Purpose |
+| --- | --- |
+| `project` | Stable project identity. |
+| `template` | ZSK template id and version. |
+| `providers` | Connection profiles such as Jira, Confluence, GitHub, GitLab, Figma, or MCP-backed tools. |
+| `resources` | Durable entry-source intents to prepare, such as repository roots, issue feeds, document entry pages, design entry nodes, or command/MCP outputs. |
+| `routes` | Delivery rules from prepared resources to module or shared consumption surfaces. |
+| `modules` | Module discovery settings and optional module registry entries. |
+| `customize` / `staffing` | Pointers to role, workflow, provider, or gate policy files. |
+| `sources` | Compatibility source tree for durable grouped prepare entries. Auto-discovered children stay in draft evidence until promoted. |
+
+## Materialization
+
+The workspace does not pre-create resource directories.
+
+- `resources` or durable `sources` entries produce `.zsk/raws/**` snapshots after sync.
+- `zsk prepare draft` writes candidate entries to
+  `.zsk/evidence/prepare/{run}/config-draft.yaml` and review guidance to
+  `source-promotion-suggestions.md`; it must not update `.zsk/config.yaml`.
+- `routes` entries may update `.zsk/modules/<module>/_issues/**`,
+  `.zsk/modules/<module>/sources.yaml`, or other controlled artifacts.
+- `zsk prepare sync` writes `.zsk/evidence/prepare/sync-report.md`.
+- Missing provider credentials or route conflicts must be visible in the report
+  with a clear state, reason, output path, and next action.
+
+## Resource Output
+
+Default raw output is derived from `type + id`, but a resource may override it
+with `output.rawPath`. Keep these entries at the authority-entry level; do not
+hand-maintain every child page, issue, Figma node, or file found under the entry.
+
+```yaml
+resources:
+  - id: my-bugs
+    type: issues
+    provider: jira
+```
+
+Default output:
+
+```text
+.zsk/raws/issues/my-bugs/
+```
+
+Only configured resources with produced snapshots create directories.
+
+## Credential References
+
+`.zsk/config.yaml` stores env var names only. Put the values in the runtime
+environment, for example by exporting them from `~/.zshrc` before launching the
+shell that runs `zsk`.
+
+```yaml
+providers:
+  jira:
+    type: issues
+    adapter: jira
+    baseUrl: https://jira.example.com
+    auth:
+      env: ACCESS_TOKEN
+  confluence:
+    type: document
+    adapter: confluence
+    baseUrl: https://confluence.example.com
+    auth:
+      usernameEnv: CONFLUENCE_USER
+      passwordEnv: CONFLUENCE_PASSWORD
+```
+
+## Adapter Fallbacks
+
+`source.adapter` is reserved for built-in source adapters: `jira`,
+`confluence`, `gitlab`, and `figma`. Runtime tools such as `playwright_cli`,
+`playwright_mcp`, `browser_use`, and `computer_use` are fallback or observation
+surfaces, not provider adapters.
+
+Use `fallback` when a source may need a runtime-assisted acquisition path:
+
+```yaml
+sources:
+  product:
+    prd:
+      type: prd
+      origin:
+        kind: url
+        url: https://example.com/prd
+      fallback:
+        acquisition: [playwright_cli]
+        observation: [computer_use]
+```
+
+Compatibility note: if an older config puts `playwright_cli` or `computer_use`
+under `adapter`, config check accepts it with a warning and treats it as a
+fallback alias. `computer_use` remains observation-only; prepare sync will not
+silently launch a Computer Use session.
+
+## Demo Auth
+
+Authenticated demos should configure login resources by reference. Keep real
+credentials in local env files such as `~/.zshrc`; put only env key names in
+`.zsk/config.yaml`.
+
+```yaml
+automation:
+  demo:
+    auth:
+      required: true
+      loginUrl: http://localhost:3000/login
+      storageState: .zsk/modules/{module}/_playwright/.auth/user.json
+      envFiles:
+        - ~/.zshrc
+      env:
+        username: DEMO_USERNAME
+        password: DEMO_PASSWORD
+      selectors:
+        username: input[name="username"]
+        password: input[type="password"]
+        submit: button[type="submit"]
+```
+
+`zsk demo auth -m <module>` writes a module-local Playwright login helper that
+loads those env files, fills configured fields when selectors are available,
+then saves reusable `storageState`. Generated demo specs reuse the same
+`storageState` and fail fast if they are redirected back to a login page.

package/templates/project-init/.zsk/docs/PROJECT-CONFIG.md

@@ -19,9 +19,12 @@ Use this layer to answer three questions before execution:
 | Path | Purpose |
 | --- | --- |
 | `.zsk/config.yaml` | Machine-readable project config and path authority |
-| `.zsk/docs/` | Project-level docs such as this file and `SYSTEM-SPEC.md` |
+| `.zsk/roles.yaml` | Project staffing policy and role pool overrides |
+| `.zsk/docs/` | Project-level docs such as this file, `SYSTEM-SPEC.md`, `CONFIG-SCHEMA.md`, and `SECURITY.md` |
 | `.zsk/modules/{module}/` | Module `module.yaml`, `proposal.md`, `spec.md`, `design.md`, `tasks.md` |
-| `.zsk/raws/` | Immutable raw fact sources and manifest/index files |
+| `.zsk/raws/` | Entry-driven Resource Snapshot Library |
+| `.zsk/evidence/prepare/{run}/config-draft.yaml` | Auto-discovered source candidate tree for review |
+| `.zsk/evidence/prepare/{run}/source-promotion-suggestions.md` | Human review queue for promoting candidates into config |
 | `.zsk/modules/{module}/_issues/` | Module-private issue records, created on demand |
 | `.zsk/modules/{module}/_evidence/` | Module-private evidence, screenshots, traces, logs, and verification artifacts, created on demand |
 | `.zsk/modules/{module}/_playwright/` | Module-specific Playwright specs, plans, auth state, results, reports, and execution records, created on demand |
@@ -33,12 +36,13 @@ Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are not default write tar
 
 1. `.zsk/config.yaml`
 2. `.zsk/docs/SYSTEM-SPEC.md`
-3. Project resource origins listed under `.zsk/config.yaml#sources`
-4. `.zsk/raws/manifest.json` and `.zsk/raws/index.md`
-5. `.zsk/modules/{module}/module.yaml`
-6. `.zsk/modules/{module}/spec.md`
-7. `.zsk/modules/{module}/design.md`
-8. Runtime evidence under module `_evidence` / `_playwright` or shared `.zsk/evidence` / `.zsk/playwright`
+3. Project provider/entry-source/route intent in `.zsk/config.yaml`
+4. Prepare drafts and promotion suggestions under `.zsk/evidence/prepare/{run}/`
+5. Materialized resource snapshots under `.zsk/raws/**`
+6. `.zsk/modules/{module}/module.yaml`
+7. `.zsk/modules/{module}/spec.md`
+8. `.zsk/modules/{module}/design.md`
+9. Runtime evidence under module `_evidence` / `_playwright` or shared `.zsk/evidence` / `.zsk/playwright`
 
 When sources conflict, record the conflict under the module `_issues` directory, or shared `.zsk/issues` only for cross-module/global issues, and update the affected module docs with a Documentation Feedback note or an explicit no-update rationale.
 
@@ -53,21 +57,31 @@ Every module stage document is a handoff contract:
 
 If a document cannot answer its stage questions, stop and record the missing source, decision, blocker, or issue instead of filling the template.
 
-## Preproposal Raw Artifacts
+## Resource Snapshot Contract
 
-`preproposal` may create living raw artifacts under `.zsk/raws/prepare/**` when a
-brief request lacks reviewed product, roadmap, UX, design-source, or source
-readiness material.
+`prepare sync` materializes configured resources under `.zsk/raws/**`; init does
+not create resource subdirectories or empty indexes.
 
-- Product direction and roadmap seeds live under `.zsk/raws/prepare/product/**`.
-- UX readiness and interaction handoff live under `.zsk/raws/prepare/ux/**`.
-- Design-source needs and provider source maps live under `.zsk/raws/prepare/design/**`.
-- Checkpoint review evidence lives under `.zsk/evidence/preproposal/{run}/`.
+Configure durable entry sources in `.zsk/config.yaml`, not every child artifact
+found below an entry. For example, one Confluence space/page entry can be the
+authority for a product area; child pages discovered from that entry first land
+in `.zsk/evidence/prepare/{run}/config-draft.yaml` and
+`source-promotion-suggestions.md`. Promote a child into `.zsk/config.yaml` only
+after a human confirms it is stable, reusable, and worth tracking as an
+authority source.
 
-Module `proposal.md`, `spec.md`, `design.md`, and `tasks.md` should reference
-reviewed revisions from these raw artifacts instead of copying their full
-contents. A later interaction change updates the raw artifact first, then routes
-impact to the affected module stage.
+Default resource output is derived from `type + id`, for example:
+
+| Resource | Default Snapshot Path |
+| --- | --- |
+| `type: repository`, `id: core-api` | `.zsk/raws/repositories/core-api/` |
+| `type: issues`, `id: my-bugs` | `.zsk/raws/issues/my-bugs/` |
+| `type: document`, `id: role-prd` | `.zsk/raws/document/role-prd/` |
+
+Each snapshot directory should contain a human-readable `snapshot.md`, redacted
+`metadata.yaml`, ignored `source.json`, and ignored `assets/` when raw payloads
+or exports exist. Directory-style resources such as git submodules may also
+contain a `repository/` checkout.
 
 ## Prepare Capture Strategy
 
@@ -76,16 +90,21 @@ not a requirement author, interaction designer, code designer, or task planner.
 
 Use this order for source capture:
 
-1. Register stable origins in `.zsk/config.yaml#sources`.
-2. Run `zsk prepare plan` to classify ready, stale, blocked, and ambiguous
+1. Register provider profiles, entry sources, and routes in `.zsk/config.yaml`.
+2. Run `zsk prepare draft` to write a candidate `config-draft.yaml` and
+   `source-promotion-suggestions.md`; review these before applying changes to
+   `.zsk/config.yaml`.
+3. Run `zsk prepare plan` to classify ready, stale, blocked, and ambiguous
    sources before writing snapshots.
-3. Run `zsk prepare auth-check` for private URLs so credentials are verified
-   without writing source content.
-4. Run `zsk prepare sync` for local/provider/export sources, adding
+4. Run `zsk prepare auth-check` for private URLs so credentials are verified
+   without writing source content. The command reads exported env vars such as
+   `ACCESS_TOKEN`, `CONFLUENCE_USER`, and `CONFLUENCE_PASSWORD`; it never reads
+   `~/.zshrc` directly or prints secret values.
+5. Run `zsk prepare sync` for local/provider/export sources, adding
    `--allow-network`, `--browser`, and `--auth-state` only when that acquisition
    is intentional.
-5. Review `.zsk/evidence/prepare/{run}/adapter-results/` and
-   `downstream-impact.md` before downstream stages consume the snapshot.
+6. Review `.zsk/evidence/prepare/sync-report.md` before downstream stages
+   consume the snapshot.
 
 For Figma or similar design tools, prefer provider API/export payloads, raw node
 exports, screenshots/assets, and local design-source maps over a bare page URL.
@@ -98,7 +117,9 @@ narrower page/frame split is justified in the raw artifact.
 
 ## Maintenance Checklist
 
-- Update `.zsk/config.yaml` when paths, tools, or source origins change.
+- Update `.zsk/config.yaml` when providers, durable entry sources, routes, modules, paths, or tools change.
+- Review `config-draft.yaml` and `source-promotion-suggestions.md` before
+  promoting discovered child resources into `.zsk/config.yaml`.
 - Keep project-wide reusable rules in `.zsk/docs/SYSTEM-SPEC.md`.
 - Keep module-specific decisions in `.zsk/modules/{module}/`.
 - Keep shared raw source facts under `.zsk/raws/`.

package/templates/project-init/.zsk/docs/README.md

@@ -0,0 +1,10 @@
+# ZSK Docs
+
+Project-wide governance documents live here.
+
+- `PROJECT-CONFIG.md` explains workspace layout and source authority.
+- `SYSTEM-SPEC.md` records project-wide operating rules.
+- `CONFIG-SCHEMA.md` explains the local config shape used by this project.
+- `SECURITY.md` records raw payload, credential, and commit policy.
+
+Keep module-specific proposal/spec/design/tasks under `.zsk/modules/<module>/`.

package/templates/project-init/.zsk/docs/SECURITY.md

@@ -0,0 +1,34 @@
+# Security
+
+`prepare sync` can touch private provider data. Keep security rules visible in
+the project, not only in implementation.
+
+## Credentials
+
+- Do not write tokens, cookies, passwords, or authorization headers in
+  `.zsk/config.yaml`.
+- Reference credentials by environment variable or global profile.
+- Shell startup files such as `~/.zshrc` may export those variables, but ZSK
+  only reads the already exported `process.env` values. It does not parse shell
+  startup files or persist their values.
+- For Jira, use a token env such as `ACCESS_TOKEN`.
+- For Confluence instances that do not support access tokens, use Basic auth
+  env names such as `CONFLUENCE_USER` and `CONFLUENCE_PASSWORD`.
+- Readiness reports may say that an env var or profile is present, but must not
+  print secret values.
+
+## Raw Payloads
+
+- `source.json` is ignored by default.
+- `assets/` is ignored by default.
+- `snapshot.md`, `metadata.yaml`, and `sync-report.md` must be redacted before
+  write.
+- `output.commitRaw: true` is required before raw payloads become commit
+  candidates.
+
+## Redaction
+
+Provider payloads must pass through a sanitizer before writing `source.json`,
+`snapshot.md`, `metadata.yaml`, or reports. At minimum, redact credential-shaped
+fields such as `token`, `cookie`, `authorization`, `password`, and provider
+session headers.

package/templates/project-init/.zsk/docs/SYSTEM-SPEC.md

@@ -6,10 +6,11 @@ This document captures project-wide rules that should guide module work.
 
 The `.zsk/` workspace is this project's Halcyon layer. It keeps AI execution grounded by separating:
 
-- raw facts under `paths.raws`;
+- config-declared entry sources and materialized snapshots under `paths.raws`;
 - project-wide rules under `paths.docs`;
 - module-owned stage contracts under `paths.modules`;
-- runtime evidence under module `_evidence` or shared `paths.evidence`;
+- prepare drafts/promotion suggestions and runtime evidence under module
+  `_evidence` or shared `paths.evidence`;
 - issue records under module `_issues` or shared/global `paths.issues`;
 - Playwright plans/specs/results under module `_playwright` or shared `paths.playwright`.
 
@@ -19,17 +20,21 @@ Agents must use the smallest sufficient lane: read local sources first, run dete
 
 - `paths.docs` stores project-level docs only.
 - `paths.modules` stores module source-of-truth docs.
-- `paths.raws` stores immutable shared source snapshots and manually provided fact sources.
-- `preproposal` may add candidate/generated product, roadmap, UX, and design-source readiness resources under `paths.raws` only when provenance, assumptions, review checkpoint status, and blockers are explicit. When a target module is specified, raw topics default to the module id and must name any narrower page/frame split rationale.
+- `paths.raws` stores shared Resource Snapshots produced from configured entry sources.
+- Raw resource directories are not pre-created. A child directory under `paths.raws` must correspond to a configured resource output and a real sync result.
+- `paths.evidence/prepare/{run}/config-draft.yaml` and
+  `source-promotion-suggestions.md` are the review queue for discovered child
+  sources. They do not change `.zsk/config.yaml` until a human promotes selected
+  entries.
 - Module `_issues` stores module-specific actionable issue records; `paths.issues` is created on demand only for shared/global indexes or cross-module issues.
 - Module `_evidence` stores module-specific runtime evidence and verification artifacts; `paths.evidence` is created on demand only for shared/global evidence.
 - Module `_playwright` stores module-specific Playwright specs, plans, auth state, results, reports, and execution records; `paths.playwright` is created on demand only for shared Playwright assets.
 
-Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are legacy or export surfaces, not default zsk write targets.
+Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are export surfaces, not default zsk write targets.
 
 ## Testing Assets
 
-Original QA, acceptance, release, and manually supplied test cases belong in configured project sources and may be snapshotted under `paths.raws`, normally `.zsk/raws/qa/testing`. Module-derived test plans and Playwright specs belong under module `_playwright` unless they are intentionally shared under `paths.playwright`.
+Original QA, acceptance, release, and manually supplied test cases belong in configured resources and may be snapshotted under `paths.raws`. Module-derived test plans and Playwright specs belong under module `_playwright` unless they are intentionally shared under `paths.playwright`.
 
 ## Completion Feedback
 
@@ -44,9 +49,16 @@ Runtime evidence should be linked from docs, not embedded in docs.
 
 ZSK stage documents are decision artifacts. They are complete only when the next stage can act without hidden chat context.
 
+Every stage document must include `Output Quality Check` near the top, after the
+title/summary and before the body. The block is a compact quality status, not a
+log. It uses stable fields in order: `status`, `owner`, `source_basis`,
+`blocking_items`, and `next_action`; optional fields are `waiver` and
+`updated_at`. Valid statuses are `PASS`, `NEEDS_CLARIFICATION`,
+`NEEDS_REPAIR`, `BLOCKED`, and `WAIVED`.
+
 | Stage | Document Mode | Must Prove |
 | --- | --- | --- |
-| `prepare` | Evidence report | Source origins, freshness, conflicts, and raw snapshot paths are known before planning. |
+| `prepare` | Evidence report | Provider readiness, resource freshness, route results, conflicts, and raw snapshot paths are known before planning. |
 | `preproposal` | Decision brief | Product direction, MVP/phase split, UX/design readiness, assumptions, risks, and readiness review are complete before proposal when no reviewed source pack exists. |
 | `proposal` | Decision brief | Problem, user/business outcome, scope, non-goals, risks, and success criteria are explicit. |
 | `spec` | Behavior contract | FR/NFR, scenarios, edge cases, and acceptance criteria are observable and source-linked. |
@@ -61,16 +73,21 @@ ZSK stage documents are decision artifacts. They are complete only when the next
 Each stage document must separate facts, decisions, assumptions, open questions,
 evidence, and next action. Do not leave template filler, untraceable "best
 practice" claims, vague tasks, or unresolved contradictions in a stage artifact.
-Each stage challenge must also align terminology against project context,
+Each `Output Quality Check` must also align terminology against project context,
 configured raw sources, existing artifact IDs, and implementation names when
 implementation-facing work is touched. Conflicting, overloaded, stale, or
 translated terms must be recorded as a blocker or repaired by the owning stage.
 
+When `Output Quality Check` is `NEEDS_CLARIFICATION`, the owning stage uses
+Clarification Prelude: ask one question, show a separate recommendation, refine
+one `待写入确认表达：`, write the accepted expression to `CLAR`, update the stage
+artifact and any reusable `CONTEXT.md` term, then stop after minimal validation.
+
 ## Lifecycle Ownership
 
 | Artifact / Decision | Owning Stage | Notes |
 | --- | --- | --- |
-| Source origins, acquisition plan, auth readiness, raw snapshots, manifest/index, adapter results, downstream impact evidence | `prepare` | Capture-only stage. It may classify sources as ready/stale/blocked/gap, but it does not invent requirements, interactions, architecture, or tasks. |
+| Provider profiles, durable entry-source intents, config drafts, source-promotion suggestions, acquisition plan, auth readiness, raw snapshots, route results, sync report, and downstream impact evidence | `prepare` | Capture-only stage. It may classify resources as ready/stale/blocked/conflict/gap, but it does not invent requirements, interactions, architecture, or tasks. Auto-discovered children stay advisory until human promotion into config. |
 | Product direction, roadmap, UX readiness, interaction handoff, design-source map | `preproposal` | Living raw artifacts. They may change after initial review, but each revision records source, status, impact, and affected downstream stages. |
 | Scope, non-goals, success criteria, high-level risks | `proposal` | Freezes the smallest useful problem/scope boundary before behavior is specified. |
 | FR, NFR, acceptance criteria, scenarios, edge cases | `spec` | Creates observable behavior contracts from proposal/source evidence. Missing quality targets remain `未指定` instead of invented. |

package/templates/project-init/.zsk/evidence/README.md

@@ -0,0 +1,21 @@
+# Shared Evidence
+
+Use this directory for shared evidence and reports that are not owned by a single
+module.
+
+`zsk prepare sync` writes human-readable preparation reports here, such as:
+
+```text
+.zsk/evidence/prepare/<run>/config-draft.yaml
+.zsk/evidence/prepare/<run>/source-promotion-suggestions.md
+.zsk/evidence/prepare/sync-report.md
+.zsk/evidence/prepare/blocked-resources.md
+```
+
+`config-draft.yaml` and `source-promotion-suggestions.md` are review artifacts.
+They do not mutate `.zsk/config.yaml`; selected entries must be applied only
+after human confirmation.
+
+Runtime state, temporary files, traces, videos, and raw provider payloads must
+stay out of committed evidence unless a workflow explicitly promotes a redacted
+artifact.

package/templates/project-init/.zsk/evidence/prepare/README.md

@@ -0,0 +1,22 @@
+# Prepare Evidence
+
+Prepare runs write per-run artifacts here:
+
+```text
+.zsk/evidence/prepare/<run>/
+  repo-inventory.json
+  config-draft.yaml
+  source-promotion-suggestions.md
+  acquisition-plan.json
+  blocked-sources.md
+  correspondence-questions.md
+```
+
+Default collaboration rule:
+
+- `config-draft.yaml` is a candidate tree, not an applied config.
+- `source-promotion-suggestions.md` explains which candidates are ready or need
+  review.
+- `.zsk/config.yaml` changes only after human confirmation.
+- `sync-report.md` summarizes actual materialization results after
+  `zsk prepare sync`.

package/templates/project-init/.zsk/issues/README.md

@@ -0,0 +1,10 @@
+# Global Issues
+
+Use this directory for global or cross-module issues:
+
+- missing provider credentials;
+- blocked resource preparation;
+- route conflicts across multiple modules;
+- architecture or governance blockers that are not owned by one module.
+
+Module-specific work belongs in `.zsk/modules/<module>/_issues/**`.

package/templates/project-init/.zsk/modules/README.md

@@ -0,0 +1,19 @@
+# Modules
+
+Modules are explicit business or delivery surfaces. `zsk init` does not create a
+fake default module.
+
+Create a module with:
+
+```bash
+zsk module init -m <module-id> --name "<Module Name>"
+```
+
+Module-local generated/manual artifacts use controlled underscore directories:
+
+- `_issues/` for module task cards and routed external issues.
+- `_evidence/` for module verification evidence.
+- `_playwright/` for module UI automation plans, specs, auth state, results, and
+  reports.
+
+These directories are created only when a real module and artifact exist.

package/templates/project-init/.zsk/modules/index.md

@@ -1,7 +1,11 @@
-# Module Index
+# Modules
 
-Generated and refreshed as modules are added.
+No modules are declared yet.
 
-| Module | Status | Notes |
-| --- | --- | --- |
-|  |  |  |
+Add modules in `.zsk/config.yaml` or run:
+
+```bash
+zsk module init -m <module-id> --name "<Module Name>"
+```
+
+This file is the module registry view. It is not a placeholder module.

package/templates/project-init/.zsk/raws/README.md

@@ -0,0 +1,39 @@
+# Raw Resource Snapshots
+
+`.zsk/raws` is the Resource Snapshot Library.
+
+This directory is entry-driven. Do not create empty resource type directories
+because an adapter exists. A child directory is created only when:
+
+1. `.zsk/config.yaml` declares a durable entry source, and
+2. `zsk prepare sync` produces a snapshot for that resource.
+
+Auto-discovered child pages, nodes, issues, and files should first appear in
+`.zsk/evidence/prepare/{run}/config-draft.yaml` and
+`source-promotion-suggestions.md`. Promote only human-confirmed authority
+sources back into `.zsk/config.yaml`.
+
+## Snapshot Contract
+
+```text
+.zsk/raws/<resource-kind>/<resource-key>/
+  snapshot.md
+  metadata.yaml
+  source.json
+  assets/
+```
+
+`snapshot.md` is the human-readable summary. `metadata.yaml` stores provenance,
+freshness, hashes, provider readiness, and sync state. `source.json` and
+`assets/` hold raw or semi-raw provider payloads and are ignored by default.
+
+Directory-style resources, such as git submodules, may use:
+
+```text
+.zsk/raws/repositories/<resource-key>/
+  repository/
+  snapshot.md
+  metadata.yaml
+```
+
+Generated raw indexes are created by sync only after real snapshots exist.