chore(maintenance): establish current repository owners

.github/workflows/ci.yml

@@ -45,12 +45,3 @@ jobs:
 
       - name: Verify the workspace
         run: pnpm check
-
-      - name: Upload the checked Histoire artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: ui-web-histoire
-          path: packages/web/.histoire/dist
-          if-no-files-found: error
-          include-hidden-files: true
-          retention-days: 7

.github/workflows/pages-deploy.yml

@@ -123,21 +123,6 @@ jobs:
           name: ui-web-histoire
           path: .pages-delivery/dist
 
-      - name: Reverify main before delivery
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        env:
-          RELEASE_HEAD_SHA: ${{ needs.build.outputs.head_sha }}
-        with:
-          script: |
-            const currentMain = await github.rest.git.getRef({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              ref: 'heads/main',
-            })
-            if (currentMain.data.object.sha !== process.env.RELEASE_HEAD_SHA) {
-              core.setFailed('Main changed after the Histoire build; refusing delivery.')
-            }
-
       - name: Deploy the exact Histoire release artifact
         env:
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

.github/workflows/pages-preview.yml

@@ -24,7 +24,6 @@ jobs:
       branch: ${{ steps.identity.outputs.branch }}
       head_sha: ${{ steps.identity.outputs.head_sha }}
       pull_number: ${{ steps.identity.outputs.pull_number }}
-      run_id: ${{ steps.identity.outputs.run_id }}
     steps:
       - name: Resolve the exact internal pull request
         id: identity
@@ -38,7 +37,7 @@ jobs:
               run_id: runId,
             })
             if (run.name !== 'UI checks' || run.path !== '.github/workflows/ci.yml') {
-              core.setFailed('Preview artifact must come from the trusted UI checks workflow.')
+              core.setFailed('Preview must be orchestrated by the trusted UI checks workflow.')
               return
             }
             if (run.conclusion !== 'success' || run.event !== 'pull_request') {
@@ -69,7 +68,6 @@ jobs:
             core.setOutput('branch', `pr-${pull.number}`)
             core.setOutput('head_sha', run.head_sha)
             core.setOutput('pull_number', String(pull.number))
-            core.setOutput('run_id', String(runId))
 
   deploy:
     name: ui-web preview
@@ -78,10 +76,8 @@ jobs:
       group: ui-web-preview-${{ needs.identity.outputs.pull_number }}
       cancel-in-progress: true
     permissions:
-      actions: read
       contents: read
       deployments: write
-      pull-requests: read
     runs-on: ubuntu-latest
     timeout-minutes: 20
     environment:
@@ -95,6 +91,13 @@ jobs:
           path: controller
           persist-credentials: false
 
+      - name: Checkout the exact pull-request head
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.identity.outputs.head_sha }}
+          path: candidate
+          persist-credentials: false
+
       - name: Install the pinned pnpm release
         uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         with:
@@ -105,49 +108,27 @@ jobs:
         with:
           node-version: 22.22.3
           cache: pnpm
-          cache-dependency-path: controller/pnpm-lock.yaml
+          cache-dependency-path: |
+            candidate/pnpm-lock.yaml
+            controller/pnpm-lock.yaml
 
-      - name: Install the trusted delivery toolchain
-        run: pnpm --dir controller install --frozen-lockfile
+      - name: Install the candidate and trusted delivery toolchains
+        run: |
+          pnpm --dir candidate install --frozen-lockfile
+          pnpm --dir controller install --frozen-lockfile
 
-      - name: Download the exact checked artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: ui-web-histoire
-          path: .pages-preview/dist
-          run-id: ${{ needs.identity.outputs.run_id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Reverify pull-request identity before delivery
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        env:
-          PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }}
-          PULL_NUMBER: ${{ needs.identity.outputs.pull_number }}
-        with:
-          script: |
-            const { data: pull } = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: Number(process.env.PULL_NUMBER),
-            })
-            if (
-              pull.state !== 'open' ||
-              pull.base.ref !== 'main' ||
-              pull.head.sha !== process.env.PREVIEW_HEAD_SHA ||
-              pull.head.repo?.full_name !== `${context.repo.owner}/${context.repo.repo}`
-            ) {
-              core.setFailed('Pull-request identity changed after artifact selection.')
-            }
+      - name: Build the exact-head Histoire preview
+        run: pnpm --dir candidate story
 
-      - name: Deploy the checked Histoire artifact
+      - name: Deploy the exact-head Histoire preview
         env:
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           PREVIEW_BRANCH: ${{ needs.identity.outputs.branch }}
           PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }}
         run: >-
           pnpm --dir controller exec wrangler pages deploy
-          "$GITHUB_WORKSPACE/.pages-preview/dist"
+          "$GITHUB_WORKSPACE/candidate/packages/web/.histoire/dist"
           --project-name="${{ vars.CLOUDFLARE_PAGES_PROJECT }}"
           --branch="$PREVIEW_BRANCH"
           --commit-hash="$PREVIEW_HEAD_SHA"

.gitignore

@@ -1,33 +1,38 @@
-# package files
-dist/
-node_modules/
-package-lock.json
-yarn.lock
-
-# IDE files
-.vscode/*
+# package files
+dist/
+node_modules/
+package-lock.json
+yarn.lock
+
+# IDE files
+.vscode/*
 !.vscode/*.example.jsonc
 !.vscode/*.code-snippets
 !.vscode/extensions.json
 !.vscode/settings.json
-
-# temp files
-tmp
-
-# build files
-*.tgz
-stats.html
-
-# logs
-debug.log
-
-# test coverage
-coverage/
-.nyc_output/
-
-# histoire
-.histoire/
-
-# images
-*.png
+
+# temp files
+tmp
+
+# build files
+*.tgz
+stats.html
+
+# logs
+debug.log
+
+# test coverage
+coverage/
+.nyc_output/
+
+# histoire
+.histoire/
+
+# images
+*.png
 *.jpg
+
+# svc:begin local-config sha256=0cb2591848c4e5675766aa516f16dfb9981fc52e1dcbadd8cec89b6982db927d
+svc.local.json
+AGENTS.local.md
+# svc:end local-config

AGENTS.md

@@ -1,27 +1,64 @@
-# `@inkcre/ui` coding guide
+# InKCre UI
 
 This repository owns the InKCre design system and UI libraries.
 
-## Project Structure
+Reason in English. Communicate with humans in Chinese.
 
-- `packages/`: this is a monorepo
-  - `web`: `@inkcre/ui-web`, the InKCre UI library for web projects
-- `tokens/`
-  - `inkcre.tokens.json`: Design tokens follows W3C DTCG format
-- `scripts/`
-  - `build-tokens.ts`: Transform design tokens to code
+## Repository Map
+
+- `packages/web/`: `@inkcre/ui-web`, its public components, styles, stories,
+  generated consumer skill, and package-local instructions.
+- `tokens/inkcre.tokens.json`: W3C DTCG design-token source.
+- `scripts/`: deterministic token, package-metadata, Agent Skill, contract, and
+  release preparation commands.
+- `docs/index.md`: durable documentation navigation.
+- `tasks/`: volatile task packets retained only while their parent task is active.
+
+## Knowledge Owners
+
+- Repository and package entry points: `README.md` and `packages/web/README.md`.
+- Public package API: package exports, component manifest, TypeScript source,
+  generated declarations, and styles.
+- Component usage evidence: `packages/web/stories/`.
+- UI consumer Agent guidance: `packages/web/skill.seed.json` and the generated
+  `packages/web/skills/ui-web/` artifact.
+- Package migration contract: `packages/web/MIGRATION.md`.
+- Build, release, preview, and production behavior: package scripts, repository
+  scripts, and `.github/workflows/`.
+- Repeated subtree hazards: the nearest local `AGENTS.md`.
 
 ## Coding Guidelines
 
 - [Coding for Human](/.github/instructions/coding-for-human.instructions.md)
 
-## Development Workflows
+## Development Workflow
 
 - Follow the organization-wide [Git and GitHub Governance](https://github.com/InKCre/.github/blob/main/GOVERNANCE.md)
   and [contribution workflow](https://github.com/InKCre/.github/blob/main/CONTRIBUTING.md) for branches, pull requests,
   release authority, and delivery boundaries; repository-local documents own exact commands.
-- Package manager is PNPM
-- Use changeset to summarize your changes (run `pnpm changeset` after you made changes.)
+- Runtime: Node.js 22.22.3; package manager: pnpm 11.17.0.
+- Install with `pnpm install --frozen-lockfile`; run the full contract with
+  `pnpm check`.
+- Use `pnpm changeset` for an observable published-package change.
+- Generated tokens, package metadata, and `skills/ui-web` are checked-in
+  projections. Change their source owner and run `pnpm generate`; do not edit
+  generated output directly.
 - Follow the organization-wide [Verification and Test Policy](https://github.com/InKCre/.github/blob/main/TESTING.md).
   This repository prefers type-check, lint, generated-contract checks, story builds, and real
   consuming-page review; it currently admits no automated unit/component suite.
+- Require explicit Human authorization before commit, push, publication, or
+  external repository/settings mutation.
+
+<!-- svc:begin -->
+## SVC
+
+Use `svc --help` or `svc <command> --help`.
+
+- `svc status`: inspect project state
+- `svc lookup`: read SVC guidance
+- `svc task init`: create a task packet
+- `svc task grow`: inspect packet shape without changing files
+- `svc dev`: manage declared development targets
+
+If `AGENTS.local.md` exists, read it after this file. It is ignored local guidance; shared rules belong here.
+<!-- svc:end -->

README.md

@@ -60,11 +60,12 @@ coverage, and generated Agent Skills.
 
 ## Histoire delivery
 
-`UI checks` builds Histoire as part of the repository contract. Successful
-same-repository pull requests publish that checked output to the stable
-`pr-N.design-dd4.pages.dev` preview alias. Closing the pull request replaces
-the alias with a noindex marker; Cloudflare retains older immutable deployment
-URLs as platform history.
+`UI checks` validates Histoire as part of the repository contract. After a
+successful same-repository run, the trusted Preview workflow checks out that
+exact pull-request head, builds Histoire itself, and publishes it to the stable
+`pr-N.design-dd4.pages.dev` preview alias. Closing the pull request replaces the
+alias with a noindex marker; Cloudflare retains older immutable deployment URLs
+as platform history.
 
 A protected `main` push builds Histoire again as a focused release, transfers
 the exact same-run artifact to the deployment job, and publishes it to

docs/index.md

@@ -0,0 +1,19 @@
+# Documentation
+
+## Navigation
+
+- [Repository overview](../README.md)
+- [Web package usage and development](../packages/web/README.md)
+- [Package migration contract](../packages/web/MIGRATION.md)
+- [UI Web Agent Skill generation](../scripts/build-agent-skills.md)
+
+Public component and styling facts are owned by source, package exports,
+generated declarations, stories, and the package consumer skill. Delivery
+behavior is owned by package scripts, repository scripts, and GitHub workflows;
+this directory does not copy those executable contracts.
+
+<!-- svc:begin navigation sha256=7f7f63d0b8989624f57bd21b82b2ac2d05e4445edfd5af4bc3742996f0754bda -->
+## SVC Corpus
+
+Use `svc lookup` when packaged Sustainable Vibe Coding Corpus guidance is relevant, and discover its browse/search/read grammar through `svc lookup --help`. Project documentation outside this marked block remains Consumer-owned.
+<!-- svc:end navigation -->