tink-harness 1.0.0 → 1.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tink",
-  "description": "A small harness layer for Claude Code.",
-  "version": "1.0.0",
+  "description": "A small harness layer for Claude Code and Codex.",
+  "version": "1.2.0",
   "author": {
     "name": "dotori"
   }

package/CHANGELOG.md

@@ -2,11 +2,73 @@
 
 All notable changes to Tink are tracked here.
 
-## [Unreleased]
-
-### Planned (v1.1)
-
-- Layered scope model: merge `global` (`~/.tink/`) + `repo` (`.tink/`) + `local` (`.tink/local/` or `.tink/settings.local.json`) following the Claude Code settings pattern. Tracked separately.
+## [Unreleased]
+
+No unreleased changes yet.
+
+
+## [1.2.0] - 2026-06-07
+
+### Added
+
+- Codex autocomplete aliases matching the Claude Code command surface: `$tink:cast`, `$tink:verify`, `$tink:list`, `$tink:frog`, `$tink:weave`, `$tink:setup`, and `$tink:update`.
+- Contract-first context artifacts for non-trivial runs: `context-pack.md`, `context-map.json`, and `excluded-context.md`.
+- Repo Signal fixtures and documentation so `/tink:cast` can select relevant tests, schemas, sync partners, and verification hints without adding a new `tink index` command.
+- Verify Runner schema and fixtures for `.tink/current/verification.json`, including pass, fail, blocked, skipped, final report, notes summary, and maintenance signal behavior.
+- MCP Safe Profile documentation and external-context profile schema support for sources such as Figma, GitHub, official docs, dashboards, API responses, screenshots, attachments, and runbooks.
+- Compatibility policy documenting that new Tink work must support Claude Code and Codex, plus macOS and Windows.
+- PR history draft for this release in `docs/pr/2026-06-07-v1.2.0.md`.
+
+### Changed
+
+- Codex documentation and installer next-step guidance now prefer `$tink:*` spelling while keeping legacy `$tink <action>` prompts compatible.
+- Project guidance now uses lower-case `templates/codex/skills/` and the actual `.claude/` / `.claude-plugin/` paths so Mac/Linux case-sensitive filesystems match the documented structure.
+- Codex skill display is focused on action aliases only; shared Codex rules now live in non-visible `tink-core/RULES.md`.
+- `/tink:cast` records included, excluded, and external context more explicitly, including sensitivity, confidence, source handles, and verification hints.
+- `/tink:verify` now uses one portable runner model for Claude Code `/tink:verify` and Codex `$tink:verify`.
+- README and Korean README now explain the 1.2.0 release highlights and point to compatibility, repo signal, and MCP Safe Profile docs.
+
+### Fixed
+
+- Existing Codex installs that still have the old visible `skills/tink/SKILL.md` directory are cleaned up during install/update when it is recognized as the legacy Tink skill.
+
+### Removed
+
+- Removed the old installable Codex `tink` skill surface so the picker no longer shows duplicate or awkward `Tink: Tink` entries.
+
+
+## [1.1.1] - 2026-05-26
+
+### Added
+
+- Small Writ-inspired rule selection: rule graph nodes now distinguish `mandatory` and `retrievable` guidance with phase, budget cost, and keyword metadata.
+- Current-run `session.json` schema so Tink can record `loaded_rule_ids_by_phase` and avoid repeating the same rule guidance during a run.
+- Verification evidence and friction templates: `/tink:verify` now documents `.tink/current/verification.json` evidence and `.tink/maintenance/friction.jsonl` failure signals.
+
+### Changed
+
+- `/tink:cast`, `/tink:verify`, and `/tink:weave` now describe the smaller rule-loading path: mandatory first, keyword retrieval second, phase dedupe, compact evidence, then repeated-friction promotion through weave.
+- README and graph docs now explain the compact rule graph, verification evidence, and friction signal flow.
+
+
+## [1.1.0] - 2026-05-26
+
+### Added
+
+- Contract-first run model: `/tink:cast` now writes `.tink/current/contract.json` for non-trivial runs so task type, risks, success conditions, forbidden actions, verification, and evidence are structured before harness bodies are loaded.
+- `/tink:verify` command: runs the checks promised in the current contract, records compact evidence, and feeds failed checks into weave as `check_failed` signals.
+- Repo-local rule graph templates in `.tink/rules/index.json`, plus `contract.schema.json`, so Tink can select relevant harnesses, checks, and opt-in guard candidates without loading large Markdown by default.
+- Opt-in guard templates for repeated failures that should become real Claude Code hook boundaries after explicit approval.
+- Documentation for graph contracts, verification, and guard promotion.
+
+### Changed
+
+- `/tink:weave` can now classify improvements as harness edits, rule graph updates, or opt-in hook guard candidates.
+- Hook recommendation script now uses readable multilingual messages and keeps the default hook advisory-only.
+
+### Planned
+
+- Layered scope model: merge `global` (`~/.tink/`) + `repo` (`.tink/`) + `local` (`.tink/local/` or `.tink/settings.local.json`) following the Claude Code settings pattern. Tracked separately.
 
 
 ## [1.0.0] - 2026-05-25

package/README.ko.md

@@ -2,25 +2,11 @@
   <img src=".github/assets/hero.gif" alt="Tink Hero Banner" width="100%">
 </p>
 
-<h1>
-  <strong>Tink</strong>
-</h1>
+# Tink
 
-<p>사람과 함께 일하며 함께 자라는 하네스</p>
+Claude Code와 Codex를 위한 작은 하네스 레이어입니다.
 
-<p>
-  Tink는 작업에 맞는 하네스를 고르고, 작업에 맞는 하네스를 만들기도 하며, 하네스를 개선 및 제거도 합니다.
-</p>
-
-<p>
-  <em>Tink는 <strong>knit(뜨개질)</strong>을 거꾸로 한 이름입니다. 엉킨 작업 흐름을 풀고, 더 나은 흐름으로 다시 뜨개질해 묶어준다는 뜻입니다. 동시에 곁에 있는 작은 조력자 팅커벨에 대한 오마주이기도 합니다.</em>
-</p>
-
-<p>
-  <a href="https://github.com/dotoricode/tink-harness/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/dotoricode/tink-harness/ci.yml?branch=main&label=ci" alt="CI"></a>
-  <a href="https://github.com/dotoricode/tink-harness/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dotoricode/tink-harness" alt="License"></a>
-  <a href="https://github.com/dotoricode/tink-harness/stargazers"><img src="https://img.shields.io/github/stars/dotoricode/tink-harness?style=social" alt="GitHub stars"></a>
-</p>
+Tink는 지금 작업에 맞는 하네스를 고르고, 실행 상태를 보이게 만들고, 실제 사용 중 생긴 실패와 피드백으로 하네스 세트를 개선합니다.
 
 [English](README.md) · **한국어**
 
@@ -28,196 +14,106 @@
 
 ## 왜 만들었나
 
-요즘 새로운 AI 하네스가 거의 매일 등장합니다. 그중 상당수는 저에게 정말 유용했습니다.
-
-처음에는 하나씩 써보면서 저에게 맞는 것만 남겼습니다. 그런데 여러 개를 섞을수록 환경이 점점 엉켜갔습니다. 매번 처음부터 다시 정리하기가 지쳐서, 결국 제가 이해하고 통제할 수 있는 skill 기반 흐름으로 돌아갔습니다.
-
-그 뒤로 한동안 Hermes Agent를 썼습니다. 그때 마음에 남은 것은, 쓸수록 시스템이 나아진다는 점이었습니다. 반복되는 작업이 다시 쓸 수 있는 skill이 되고, 실수가 기억이 되며, 시스템이 사용하는 사람에게 천천히 맞춰져 갔습니다.
+새로운 AI 코딩 하네스와 워크플로는 계속 늘어납니다. 좋은 것도 많지만, 여러 개를 섞다 보면 환경이 무거워지고 매번 다시 정리해야 합니다.
 
-Tink는 단순한 질문에서 시작됐습니다:
-
-> Claude Code나 Codex도 저와 함께 이렇게 자랄 수 있을까요?
-
-큰 프레임워크를 더 얹지 않고도, 에이전트를 더 늘리지 않고도. 그저 Claude나 Codex가 지금 작업에 맞는 하네스를 고르고, 맞는 게 없으면 새로 만들고, 시간이 지나며 그 모음을 더 좋게 다듬도록 돕는 방식으로요.
+Tink는 큰 프레임워크가 아닙니다. Claude Code나 Codex가 지금 작업에 필요한 절차만 고르고, 없으면 작은 임시 하네스를 만들고, 반복되는 실수만 승인 후 재사용 지식으로 남기도록 돕습니다.
 
 ## 설치
 
-Claude Code 플러그인 설치:
+Claude Code 플러그인:
 
 ```text
 /plugin marketplace add dotoricode/tink-harness
-```
-
-```text
 /plugin install tink@tink-harness
-```
-
-```text
 /reload-plugins
-```
-
-```text
 /tink:setup
 ```
 
-독립형(Standalone) 호환 설치 프로그램:
+Standalone / Codex 호환 설치:
 
 ```bash
-npx github:dotoricode/tink-harness install
+npx tink-harness@latest install
 ```
 
-독립형 설치 프로그램은 `LANG` 환경 변수를 자동으로 감지합니다(감지 실패 시 영어 기본값). 강제로 지정하려면 `--lang=en|ko|zh`를 넘기세요.
+설치 중 `Claude Code`, `Codex`, 또는 둘 다를 선택할 수 있습니다. Codex에서는 `$tink:cast <task>`로 시작합니다.
 
 ## 업데이트
 
-Claude Code 플러그인 사용자:
+Claude Code 플러그인:
 
 ```text
 /plugin marketplace update tink-harness
-```
-
-```text
 /plugin update tink@tink-harness
-```
-
-```text
 /reload-plugins
 ```
 
-업데이트 명령으로 최신 버전을 찾지 못하면, 제거 후 다시 설치하세요:
-
-```text
-/plugin uninstall tink@tink-harness
-```
-
-```text
-/plugin install tink@tink-harness
-```
-
-기존 독립형 설치를 업데이트하려면(사용자 수정 파일은 유지됩니다):
+Standalone / Codex:
 
 ```bash
-npx github:dotoricode/tink-harness update
+npx tink-harness@latest update
 ```
 
-## 명령
-
-Tink는 명령 체계를 최소한으로 유지합니다.
-
-Tink는 플러그인 우선 구조이며, 모든 명령은 `tink` 네임스페이스를 사용합니다. 따라서 공개되는 명령은 `/tink:*`로 한정되고 일반 명령과의 충돌을 피할 수 있습니다.
-
-### `/tink:cast`
-
-**cast**는 뜨개질에서 첫 코를 잡는 동작입니다. 모든 작업의 시작점이 됩니다.
-
-Tink에서 `cast`는 기본 실행 흐름입니다. 작업을 읽고, 적절한 하네스를 선택하거나 초안을 만들고, 짧은 내부 검토를 거친 뒤 `.tink/current/`에 현재 작업 상태를 구성합니다. 이후 사용자 승인을 받고 안전한 첫 단계를 실행합니다.
-
-단순한 질의응답을 넘어서는 작업이라면 보통 `cast`로 시작합니다.
-
-### `/tink:frog`
-
-**frog**는 잘못 뜬 부분을 풀어내는 뜨개질 용어입니다. 실을 푸는 소리인 "rip it, rip it"에서 이름이 왔습니다.
-
-Tink에서 `frog`는:
+## 1.2.0에서 달라진 점
 
-- 더 이상 사용하지 않는 하네스
-- 다른 하네스와 역할이 겹치는 항목
-- 범위가 지나치게 넓은 하네스
-- 유지 비용 대비 효율이 낮은 하네스
+이번 릴리스는 Tink를 Claude Code와 Codex에서 같은 하네스 레이어로 쓰기 쉽게 정리합니다.
 
-를 찾아 정리를 제안합니다.
+- Codex에는 하나의 넓은 `tink` 스킬 대신 `$tink:cast`, `$tink:verify` 같은 action skill만 보이도록 설치됩니다.
+- 비단순 작업은 `context-pack.md`, `context-map.json`, `excluded-context.md`로 어떤 context를 썼고 뺐는지 남깁니다.
+- Repo Signal은 새 `tink index` 명령을 만들지 않고도 관련 테스트, 스키마, 동기화 파일, 검증 힌트를 고르는 데 쓰입니다.
+- `/tink:verify`와 `$tink:verify`는 같은 Verify Runner 모델을 쓰며 `.tink/current/verification.json`에 검증 증거를 남깁니다.
+- 외부 context는 MCP Safe Profile을 따릅니다. 가장 작은 source handle만 남기고, 신뢰도와 민감도를 표시하며, 위험하거나 너무 넓은 context는 `excluded-context.md`에 따로 기록합니다.
 
-삭제는 항상 사용자 승인 이후에만 수행됩니다.
-
-하네스 구성이 복잡하거나 정리가 필요할 때 사용합니다.
-
-### `/tink:weave`
-
-**weave**는 뜨개질을 마친 뒤 남은 실을 안쪽으로 정리해 마감하는 과정(**weave in**)에서 따온 이름입니다.
-
-Tink에서 `weave`는 실제 사용 기록, 실패 사례, 사용자 수정 내용을 바탕으로 기존 하네스를 다듬습니다.
-
-목표는 다음 실행이:
-
-- 더 명확하고
-- 더 안전하며
-- 더 검증 가능하도록
-
-개선하는 것입니다.
-
-하네스가 거의 맞지만 조금씩 어긋나기 시작할 때 사용합니다.
-
-### 기타 명령
-
-- `/tink:setup`
-  - 언어, 설치 범위, Git 추적, Hook 정책을 설정합니다.
-
-- `/tink:list`
-  - 사용 가능한 하네스와 최근 사용 내역을 확인합니다.
-
-- `/tink:update`
-  - 설치 경로를 감지하고 안전한 업데이트 방법을 안내합니다.
-
-## 동작 방식
+## 명령
 
-Tink는 사용자가 직접 확인할 수 있는 파일 구조를 사용합니다.
+Claude Code에서는 `/tink:*`, Codex에서는 `$tink:*`을 씁니다. 예전 `$tink cast` 형식도 호환되지만, 기본 안내와 자동완성 표면은 `$tink:*`입니다.
 
-- `.tink/harnesses/`
-  - 재사용 가능한 작업 하네스
+### `/tink:cast` / `$tink:cast`
 
-- `.tink/current/`
-  - 현재 실행 상태
+작업을 읽고, 필요한 하네스만 고르고, `.tink/current/` 실행 상태를 만든 뒤 첫 번째 안전한 단계를 시작합니다.
 
-- `.tink/runs/`
-  - 완료·중단·취소·교체된 실행 기록
+Tink는 이제 비단순 작업에 대해 `.tink/current/contract.json`도 만듭니다. 이 파일에는 작업 종류, 위험, 성공 조건, 금지 사항, 검증 명령이 들어갑니다.
 
-- `.tink/memory/`
-  - 승인된 실수, 선호 설정, 작업 중 얻은 교훈
+### `/tink:verify` / `$tink:verify`
 
-가장 중요한 원칙은 **승인(approval)** 입니다.
+`contract.json`에 적힌 검증을 실제로 실행하고 증거를 남깁니다.
 
-Tink는:
+릴리스, 배포, 공개 PR처럼 "된 것 같다"가 아니라 "확인했다"가 필요한 작업에서 씁니다.
 
-- 하네스 생성
-- 메모리 저장
-- 정리 작업
-- 개선 제안
+### `/tink:frog` / `$tink:frog`
 
-을 수행할 수 있지만, 실제 적용 전에는 항상 사용자 확인을 거칩니다.
+거의 쓰지 않거나 겹치거나 너무 무거운 하네스를 정리 후보로 제안합니다. 사용자 승인 없이는 삭제하지 않습니다.
 
-실행 전에는 짧은 점검 단계를 수행하며, 중요한 변경이 있을 때만 별도 제안을 표시합니다.
+### `/tink:weave` / `$tink:weave`
 
-위험이 낮은 작업은 기록된 가정을 바탕으로 계속 진행할 수 있습니다. 하지만:
+실제 실패, 반복 사용, 사용자 수정 내용을 바탕으로 하네스를 조금 더 정확하게 고칩니다. 필요한 경우 `.tink/rules/`의 rule graph나 opt-in hook guard 후보로 승격합니다.
 
-- 공개
-- 배포
-- 삭제
-- 대규모 수정
-- 되돌리기 어려운 변경
+### 기타
 
-처럼 외부 영향이 큰 작업은 반드시 명시적 승인이 필요합니다.
+- `/tink:setup` / `$tink:setup`: 언어, 설치 범위, git 추적, hook 정책 설정
+- `/tink:list` / `$tink:list`: 사용 가능한 하네스와 사용 신호 확인
+- `/tink:update` / `$tink:update`: 설치 출처를 확인하고 안전한 업데이트 안내
 
-또한:
+## 작동 방식
 
-- 새 하네스
-- 메모리 항목
-- `.claude/` 워크플로 파일
+Tink는 직접 볼 수 있는 파일을 씁니다.
 
-같은 재사용 가능한 자산을 저장할 때는 항상 별도의 승인을 다시 받습니다.
+- `.tink/harnesses/`: 재사용 가능한 작업 하네스
+- `.tink/rules/`: 계약 내용에 맞춰 필요한 하네스, 체크, guard 후보만 고르는 작은 rule graph
+- `.tink/schemas/`: `contract.json` 같은 구조화 파일의 스키마
+- `.tink/current/`: 현재 실행 상태
+- `.tink/runs/`: 완료, 중단, 취소, 교체된 실행 기록
+- `.tink/maintenance/`: 검증, friction, weave 신호 기록
+- `.tink/memory/`: 승인된 실수, 선호, 교훈
 
-현재 실행을 승인했다고 해서, 이후 설치나 영구 저장까지 자동으로 승인되는 것은 아닙니다.
+Rule graph는 작게 유지합니다. Tink는 먼저 필수 규칙을 고르고, 작업 사실이나 keyword에 맞는 선택 규칙만 가져오며, phase별로 이미 읽은 rule id를 기록해 같은 안내를 반복하지 않습니다.
 
-## Tink가 하지 않는 것
+설계 메모는 `docs/`에 둡니다. 기본 호환성 기준은 `docs/compatibility-policy.md`에 있으며, 새 작업은 Claude Code와 Codex, macOS와 Windows를 함께 고려해야 합니다. Repo Signal 동작은 `docs/repo-signals.md`에 정리되어 있고, 외부 context 안전 기준은 `docs/mcp-safe-profile.md`에 정리되어 있습니다.
 
-Tink는 다음을 목표로 하지 않습니다.
+중요한 원칙은 승인입니다. 현재 작업을 진행하는 승인과, 미래에도 재사용될 상태를 저장하는 승인은 별개입니다. 새 하네스, 메모리, rule graph, hook guard 저장은 항상 별도 승인이 필요합니다.
 
-- 코딩 에이전트
-- 워크플로 엔진
-- 멀티 에이전트 런타임
-- 프롬프트 라이브러리
-- Claude Code나 Codex 대체 도구
+## Tink가 아닌 것
 
-Tink는 Claude Code나 Codex 위에 얹는 작은 하네스 레이어입니다.
+Tink는 코딩 에이전트, 워크플로 엔진, 멀티 에이전트 런타임, 프롬프트 라이브러리가 아닙니다. Claude Code와 Codex 위에 얹는 작은 하네스 레이어입니다.
 
 ## 라이선스
 

package/README.md

@@ -6,17 +6,18 @@
   <strong>Tink</strong>
 </h1>
 
-<p>A small harness layer for Claude Code</p>
-
-<p>
-  Tink helps Claude Code choose the right harness, keep run state visible, and improve the harness set as you work.
-</p>
+<p>A small harness layer for Claude Code and Codex</p>
+
+<p>
+  Tink helps Claude Code or Codex choose the right harness, keep run state visible, and improve the harness set as you work.
+</p>
 
 <p>
   <em>Tink is <strong>knit</strong> in reverse: untying tangled workflows and knitting better ones back together. It also nods to Tinker Bell, the small helper at your side.</em>
 </p>
 
 <p>
+  <a href="https://www.npmjs.com/package/tink-harness"><img src="https://img.shields.io/npm/v/tink-harness?label=npm&color=cb3837" alt="npm version"></a>
   <a href="https://github.com/dotoricode/tink-harness/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/dotoricode/tink-harness/ci.yml?branch=main&label=ci" alt="CI"></a>
   <a href="https://github.com/dotoricode/tink-harness/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dotoricode/tink-harness" alt="License"></a>
   <a href="https://github.com/dotoricode/tink-harness/stargazers"><img src="https://img.shields.io/github/stars/dotoricode/tink-harness?style=social" alt="GitHub stars"></a>
@@ -60,13 +61,21 @@ Claude Code plugin install:
 /tink:setup
 ```
 
-Standalone compatibility installer:
-
-```bash
-npx github:dotoricode/tink-harness install
-```
-
-Standalone installer auto-detects `LANG` (English fallback). Pass `--lang=en|ko|zh` to override.
+Standalone compatibility installer:
+
+```bash
+npx tink-harness@latest install
+```
+
+Standalone installer auto-detects `LANG` (English fallback). Pass `--lang=en|ko|zh` to override.
+
+Codex skill install:
+
+```bash
+npx tink-harness@latest install
+```
+
+During install, select `Codex` when asked which agent surface to install. You can select both `Claude Code` and `Codex` in the same run. Then open Codex and use `$tink:cast <task>`.
 
 ## Update
 
@@ -94,27 +103,53 @@ If update does not find the latest version, uninstall and install again:
 /plugin install tink@tink-harness
 ```
 
-To update an existing standalone install (keeps user-modified files):
-
-```bash
-npx github:dotoricode/tink-harness update
-```
-
-## Commands
-
-Tink keeps the command surface small.
-
-Tink is plugin-first. Commands are namespaced under `tink`, so the public surface stays `/tink:*` and avoids generic command conflicts.
-
-### `/tink:cast`
+To update an existing standalone install (keeps user-modified files):
+
+```bash
+npx tink-harness@latest update
+```
+
+For Codex:
+
+```bash
+npx tink-harness@latest update
+```
+
+During update, select the installed agent surface you want to refresh.
+
+## What's new in 1.2.0
+
+This release makes Tink work as one harness layer across Claude Code and Codex.
+
+- Codex now installs focused `$tink:*` action skills instead of one broad visible `tink` skill, so the picker shows commands like `$tink:cast` and `$tink:verify` cleanly.
+- Non-trivial runs now create context artifacts: `context-pack.md`, `context-map.json`, and `excluded-context.md`.
+- Repo Signals help `/tink:cast` choose relevant tests, schemas, sync partners, and verification hints without adding a new `tink index` command.
+- `/tink:verify` and `$tink:verify` share one portable Verify Runner model and write compact evidence to `.tink/current/verification.json`.
+- External context now follows the MCP Safe Profile: include only the smallest useful source handle, mark confidence and sensitivity, exclude unsafe context visibly, and connect important claims to verification.
+
+## Commands
+
+Tink keeps the command surface small.
+
+Tink is plugin-first in Claude Code. Commands are namespaced under `tink`, so the public surface stays `/tink:*` and avoids generic command conflicts. In Codex, Tink installs matching `$tink:*` skills for autocomplete: `$tink:cast`, `$tink:verify`, `$tink:list`, `$tink:frog`, `$tink:weave`, `$tink:setup`, and `$tink:update`. Legacy `$tink cast` style prompts still work, but `$tink:*` is the preferred spelling.
+
+### `/tink:cast` / `$tink:cast`
 
 **cast** means to place the first loops on the needle (코잡기, Cast on). In knitting, casting on is the very first step — it sets the foundation for everything that follows.
 
-In Tink, `cast` is the main path. It reads the task, chooses or drafts the right harness, runs a quick internal sanity check, creates `.tink/current/` as the visible workbench, and starts the first safe step after approval.
-
-Use it when the task is more than a quick answer.
-
-### `/tink:frog`
+In Tink, `cast` is the main path. It reads the task, chooses or drafts the right harness, runs a quick internal sanity check, creates `.tink/current/` as the visible workbench, and starts the first safe step after approval.
+
+Use it when the task is more than a quick answer.
+
+### `/tink:verify` / `$tink:verify`
+
+`verify` runs the checks promised in `.tink/current/contract.json`.
+
+Tink now writes a small task contract for non-trivial runs: what kind of work this is, what must be true when it is done, what is forbidden, and which commands or manual checks prove it. `/tink:verify` uses that contract instead of relying on a vague "looks done" claim.
+
+Use it before release, publish, deploy, public PR, or any task where evidence matters.
+
+### `/tink:frog` / `$tink:frog`
 
 **frog** means to rip out stitches (풀시오, Frogging). In knitting, frogging unravels rows that went wrong — the name comes from the sound of pulling out yarn, "rip it, rip it."
 
@@ -122,7 +157,7 @@ In Tink, `frog` looks for harnesses that are unused, overlapping, too broad, or
 
 Use it when the harness set starts to feel noisy.
 
-### `/tink:weave`
+### `/tink:weave` / `$tink:weave`
 
 **weave** means to weave in the ends (실오라기 정리, Weave in). In knitting, weaving in secures the loose threads left after finishing, giving the work its final shape.
 
@@ -132,20 +167,27 @@ Use it when a harness is useful but slightly wrong.
 
 ### Other commands
 
-- `/tink:setup`: choose language, install scope, git tracking, and hook policy.
-- `/tink:list`: inspect available harnesses and recent usage signals.
-- `/tink:update`: detect install source and show the safe update command.
+- `/tink:setup` / `$tink:setup`: choose language, install scope, git tracking, and hook policy.
+- `/tink:list` / `$tink:list`: inspect available harnesses and recent usage signals.
+- `/tink:update` / `$tink:update`: detect install source and show the safe update command.
 
 ## How it works
 
 Tink uses files you can inspect:
 
-- `.tink/harnesses/`: reusable task harnesses
-- `.tink/current/`: the current run state
-- `.tink/runs/`: compact records from finished, blocked, canceled, or replaced runs
-- `.tink/memory/`: approved mistakes, preferences, and lessons
-
-The important rule is approval.
+- `.tink/harnesses/`: reusable task harnesses
+- `.tink/rules/`: a small rule graph that chooses only relevant harnesses, checks, and opt-in guard candidates
+- `.tink/schemas/`: structured file schemas, including the current run contract
+- `.tink/current/`: the current run state
+- `.tink/runs/`: compact records from finished, blocked, canceled, or replaced runs
+- `.tink/maintenance/`: verification, friction, and weave signals that help repeated failures become approved improvements
+- `.tink/memory/`: approved mistakes, preferences, and lessons
+
+The rule graph stays small on purpose. Tink loads matching mandatory rules first, retrieves only relevant optional rules by task facts or keywords, and records loaded rule ids by phase so the same guidance is not repeated in one run.
+
+Design notes live in `docs/`. The compatibility baseline is `docs/compatibility-policy.md`: every new slice should consider Claude Code and Codex, plus macOS and Windows. Repo signal behavior is described in `docs/repo-signals.md`. External context safety is described in `docs/mcp-safe-profile.md`.
+
+The important rule is approval.
 
 Tink may suggest a harness, a memory entry, a cleanup, or an improvement. Before each run is committed, Tink runs one quick sanity check and surfaces a proposal only when something important is at stake. Low-risk steps let you continue with recorded assumptions; irreversible or externally visible actions (publish, deploy, deletions, broad changes) require explicit approval. Saving anything reusable — a new harness, a memory entry, a `.claude/` workflow file — always needs its own separate approval; approving the current run does not authorize saves that future installs would inherit.
 

package/VERSIONING.md

@@ -1,8 +1,8 @@
 # Versioning
 
-Current version: `0.1.5`
+Current version: `1.2.0`
 
-Tink is pre-v1. Do not bump to `1.0.0` until the v1 release-hardening gates pass.
+Tink follows semver from `1.0.0` onward.
 
 ## Source of truth
 
@@ -15,13 +15,13 @@ Keep these versions aligned for every versioned release:
 
 Claude Code uses `.claude-plugin/plugin.json` to decide whether plugin users can receive an update. If this value does not change, `/plugin update` can report that the plugin is already latest even after new commits.
 
-## Pre-v1 bump rules
+## Bump rules
 
-Use semver, but keep everything under `1.0.0` for now.
+Use semver.
 
-- Patch, for example `0.1.1` to `0.1.4`: docs, tests, installer polish, command wording, small template fixes, non-breaking maintenance structure.
-- Minor, for example `0.1.x` to `0.2.0`: new command behavior, meaningful installer flow change, new persisted state shape, or anything existing users should deliberately notice.
-- Major `1.0.0`: only after release-hardening tests, docs truthfulness, clean install smoke, plugin validation, CI, and explicit release decision.
+- Patch, for example `1.1.2`: docs, tests, installer polish, command wording, small template fixes, non-breaking maintenance structure. Prefer a patch release for each user-visible improvement instead of letting many small changes pile up in `[Unreleased]`.
+- Minor, for example `1.1.0`: new command behavior, meaningful installer flow change, new persisted state shape, or anything existing users should deliberately notice — all backwards compatible.
+- Major, for example `2.0.0`: breaking change to the command surface, plugin contract, persisted state shape, or installer flow that existing users must migrate for.
 
 ## Release checklist
 
@@ -67,7 +67,7 @@ Claude Code plugin users:
 Standalone compatibility installer users:
 
 ```bash
-npx github:dotoricode/tink-harness update
+npx tink-harness@latest update
 ```
 
 `update` preserves user-modified files. The `--force` flag is reserved for emergency repair and is not the recommended path.