dd3ok · dd3ok · Jul 6, 2026 · Jul 5, 2026 · Jul 6, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+### Changed
+
+- Made Briefprint explicit-use in agent metadata so ordinary one-off summaries do not automatically invoke the cached briefing skill.
+- Replaced broad natural-language trigger examples with `$briefprint` invocation examples.
+- Added `disable-model-invocation: true` to the installable skill metadata for hosts that support manual-only skill invocation.
+- Documented the boundary between the static agent skill bundle and Briefprint runtime caches under `--cache-dir`.
+
 ## 0.4.0 - 2026-07-05
 
 ### Added

diff --git a/README.ko.md b/README.ko.md
@@ -110,7 +110,9 @@ skills/briefprint/
 
 repo 루트를 에이전트 스킬로 설치하지 마세요. 루트 복사 방식은 테스트, 문서, 예제, eval, 소스 코드, 검증 스크립트까지 같이 복사할 수 있습니다. 자세한 내용은 [docs/agent-skill-installation.md](docs/agent-skill-installation.md)를 보세요.
 
-Claude.ai description variant: Cache structured briefings for supplied documents, notes, logs, tickets, reports, JSON/XML, or transcripts. Use for repeated summaries, rerendering, digests, actions, risks, or metrics.
+Briefprint는 명시 호출형 스킬입니다. Codex에서는 `$briefprint`, Claude Code에서는 `/briefprint`를 사용하고, 그 밖의 호스트에서는 해당 호스트의 명시적 스킬 호출 또는 CLI를 사용하세요. 일반적인 일회성 요약이 자동으로 이 스킬을 트리거해서는 안 됩니다.
+
+Claude.ai description variant: Explicit-use cached briefings for supplied documents, notes, logs, tickets, reports, JSON/XML, or transcripts. Use for repeated summaries, rerendering, digests, actions, risks, or metrics.
 
 ## 벤치마크 결과
 
@@ -191,19 +193,32 @@ JSON, XML, HTML, `DocumentInput.source` 안에 들어있는 URL 메타데이터
 
 권장 기본값:
 
-- 반복 문서에는 `document_summaries`를 TTL 캐시로 유지
-- 템플릿 렌더링은 싸기 때문에 `rendered_outputs`는 짧게 유지
+- repo-local 캐시는 `.cache/briefprint` 아래에 두고 Git에는 올리지 않음
+- 반복 문서에는 `document_summaries`를 짧은 TTL 캐시로 유지
+- 템플릿 렌더링은 싸기 때문에 `rendered_outputs`는 더 짧게 유지
+- 평소 실행 때 `--prune-on-start`로 정리
 - 민감한 일회성 문서는 `ephemeral` 사용
 
 ```bash
 python -m document_briefing_cache.cli run \
   --input examples/mixed_documents.json \
+  --cache-dir .cache/briefprint \
   --cache-policy ttl \
-  --document-ttl 30d \
+  --document-ttl 7d \
   --output-ttl 24h \
   --prune-on-start
 ```
 
+Briefprint는 백그라운드 cleanup daemon을 돌리지 않습니다. TTL은 캐시 항목을 expired로 표시하는 값이고, 실제 파일 삭제는 `cache prune`, `--prune-on-start`, `--prune-on-exit`, delete-on-exit 정책 중 하나가 실행될 때 일어납니다. 이는 로컬 개발 도구에서 흔한 방식입니다. 생성 캐시는 disposable로 보고 Git에서 제외하며, 명시 명령이나 도구 실행 시점에 opportunistic하게 정리합니다. CI 캐시는 예외에 가깝고, GitHub Actions 같은 플랫폼은 자체 last-access/size eviction 정책을 적용합니다.
+
+보존 기간을 길게 잡는 경우는 의도적으로 persistent 캐시를 쓸 때로 제한하세요.
+
+- project-local 기본: `.cache/briefprint`, `--document-ttl 7d`, `--output-ttl 24h`, `--prune-on-start`
+- 민감한 일회성 작업: `--sensitive`
+- 장기 공유 캐시: 명시적 `--cache-policy persistent` 또는 더 긴 `--document-ttl`
+
+스킬 번들과 runtime cache는 별개입니다. 스킬 번들은 설치 시점의 정적 가이드이고, runtime cache는 `--cache-dir` 아래에 생기며 Briefprint CLI/runtime이 관리합니다. 에이전트 스킬을 설치, 업데이트, 삭제해도 runtime cache가 migrate, prune, delete 되지는 않습니다. 생성된 문서 상태에 대해 모든 agent-skill host가 공통으로 제공하는 portable automatic eviction 계약은 없으므로, 설치된 스킬 디렉터리 안에 문서 캐시를 쓰지 마세요.
+
 민감 문서:
 
 ```bash
@@ -227,9 +242,9 @@ python -m document_briefing_cache.cli run \
 캐시 관리:
 
 ```bash
-python -m document_briefing_cache.cli cache stats --cache-dir .cache --json
-python -m document_briefing_cache.cli cache prune --cache-dir .cache --older-than 30d --dry-run --json
-python -m document_briefing_cache.cli cache clear --cache-dir .cache --layer rendered_outputs --yes
+python -m document_briefing_cache.cli cache stats --cache-dir .cache/briefprint --json
+python -m document_briefing_cache.cli cache prune --cache-dir .cache/briefprint --older-than 7d --dry-run --json
+python -m document_briefing_cache.cli cache clear --cache-dir .cache/briefprint --layer rendered_outputs --yes
 ```
 
 ## LLM 요약기

diff --git a/README.md b/README.md
@@ -110,7 +110,9 @@ skills/briefprint/
 
 Do not install the repository root as an agent skill. Root-copy installers can include tests, docs, examples, evals, source code, and validation scripts. See [docs/agent-skill-installation.md](docs/agent-skill-installation.md).
 
-Claude.ai description variant: Cache structured briefings for supplied documents, notes, logs, tickets, reports, JSON/XML, or transcripts. Use for repeated summaries, rerendering, digests, actions, risks, or metrics.
+Briefprint is explicit-use by design. For Codex, use `$briefprint`; for Claude Code, use `/briefprint`; for other hosts, use the host's explicit skill invocation or the CLI when you want reusable cached document briefings. Ordinary one-off summaries should not trigger the skill automatically.
+
+Claude.ai description variant: Explicit-use cached briefings for supplied documents, notes, logs, tickets, reports, JSON/XML, or transcripts. Use for repeated summaries, rerendering, digests, actions, risks, or metrics.
 
 ## Benchmark Receipts
 
@@ -191,19 +193,32 @@ URL-bearing metadata inside JSON, XML, HTML, or `DocumentInput.source` is preser
 
 Recommended defaults:
 
-- keep `document_summaries` as a TTL cache for repeated documents,
-- keep `rendered_outputs` short-lived because template rendering is cheap,
+- keep repo-local cache under `.cache/briefprint` and keep it out of version control,
+- keep `document_summaries` as a short TTL cache for repeated documents,
+- keep `rendered_outputs` shorter-lived because template rendering is cheap,
+- run pruning during normal use with `--prune-on-start`,
 - use `ephemeral` for sensitive one-off work.
 
 ```bash
 python -m document_briefing_cache.cli run \
   --input examples/mixed_documents.json \
+  --cache-dir .cache/briefprint \
   --cache-policy ttl \
-  --document-ttl 30d \
+  --document-ttl 7d \
   --output-ttl 24h \
   --prune-on-start
 ```
 
+Briefprint does not run a background cleanup daemon. TTL values mark cache entries as expired; physical deletion happens when you run `cache prune`, enable `--prune-on-start` or `--prune-on-exit`, or use a delete-on-exit policy. This follows the common local-tooling pattern: generated caches are disposable, ignored by Git, and cleaned explicitly or opportunistically during tool runs. CI caches are the main exception; platforms such as GitHub Actions apply their own last-access and size eviction policies.
+
+Use longer retention only when the cache is intentionally persistent:
+
+- project-local default: `.cache/briefprint`, `--document-ttl 7d`, `--output-ttl 24h`, `--prune-on-start`,
+- sensitive one-off work: `--sensitive`,
+- long-lived shared cache: explicit `--cache-policy persistent` or a longer `--document-ttl`.
+
+Skill bundle and runtime cache are separate. The skill bundle is static install-time guidance; the runtime cache lives under `--cache-dir` and is owned by the Briefprint CLI/runtime. Installing, updating, or removing the agent skill does not migrate, prune, or delete runtime caches. No portable agent-skill host contract currently provides automatic eviction for generated document state, so do not write document caches into the installed skill directory.
+
 For sensitive documents:
 
 ```bash
@@ -227,9 +242,9 @@ For sensitive documents, the safe default is no persistent cache. `--sensitive`
 Cache maintenance:
 
 ```bash
-python -m document_briefing_cache.cli cache stats --cache-dir .cache --json
-python -m document_briefing_cache.cli cache prune --cache-dir .cache --older-than 30d --dry-run --json
-python -m document_briefing_cache.cli cache clear --cache-dir .cache --layer rendered_outputs --yes
+python -m document_briefing_cache.cli cache stats --cache-dir .cache/briefprint --json
+python -m document_briefing_cache.cli cache prune --cache-dir .cache/briefprint --older-than 7d --dry-run --json
+python -m document_briefing_cache.cli cache clear --cache-dir .cache/briefprint --layer rendered_outputs --yes
 ```
 
 ## LLM Summarizer

diff --git a/VALIDATION.md b/VALIDATION.md
@@ -1,6 +1,6 @@
 # Validation
 
-Last verified: 2026-07-04
+Last verified: 2026-07-05
 
 ## Environment
 
@@ -20,8 +20,8 @@ ruff check .
 
 ## Observed Results
 
-- `python -m pytest -q -p no:cacheprovider`: `164 passed, 2 skipped`
-- `python scripts\validate_skill.py --run-evals`: `OK: briefprint skill repository validated (24 test files, 9 eval cases, 9 trigger cases, 4 model benchmark cases)`
+- `python -m pytest -q -p no:cacheprovider`: `169 passed, 2 skipped`
+- `python scripts\validate_skill.py --run-evals`: `OK: briefprint skill repository validated (24 test files, 9 eval cases, 10 trigger cases, 5 model benchmark cases)`
 - `ruff check .`: `All checks passed!`
 
 `tests/test_distribution_smoke.py` remains opt-in and skips unless `DBC_RUN_INSTALLED_SMOKE=1` is set. CI or release validation should still build wheel and sdist artifacts, install each into a fresh virtual environment, and run the installed smoke test outside the repository root.

diff --git a/agents/openai.yaml b/agents/openai.yaml
@@ -6,7 +6,7 @@ interface:
   default_prompt: "Use $briefprint to summarize the supplied documents into a cached briefing and include cache stats."
 
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false
 
 metadata:
   name: "briefprint"
@@ -18,14 +18,10 @@ metadata:
     - "action_items"
     - "digest"
     - "debug"
-  triggers:
-    - "summarize these supplied documents"
-    - "brief this report from cache"
-    - "recap these meeting notes and reuse the summary"
-    - "summarize this JSON or XML payload"
-    - "create an executive digest for this document set"
-    - "rerender this briefing as digest or action_items"
-    - "summarize again without reprocessing the same documents"
+  invocation_examples:
+    - "$briefprint summarize supplied documents into a cached briefing"
+    - "$briefprint rerender cached briefing as digest"
+    - "$briefprint reuse cached document summaries"
   boundaries:
     - "Do not use for live research or current-fact lookup."
     - "Do not use for source-code review or debugging."

diff --git a/docs/agent-skill-installation.md b/docs/agent-skill-installation.md
@@ -32,6 +32,8 @@ This repository has two different install surfaces:
 
 Do not install the repository root as an agent skill. Root-copy installers can copy tests, docs, examples, eval fixtures, source code, and validation scripts into the host skill directory. Use the lightweight skill subdirectory instead.
 
+The skill bundle is static install-time guidance. Briefprint's runtime cache lives under `--cache-dir`; it is not part of the agent skill bundle. Installing, updating, or removing the agent skill does not migrate, prune, or delete runtime caches. No portable agent-skill host contract currently provides automatic eviction for generated document state. Do not write document caches into the installed skill directory.
+
 ## Bundle Contents
 
 The installable skill bundle is:

diff --git a/evals/model_invocation_benchmark_cases.json b/evals/model_invocation_benchmark_cases.json
@@ -5,27 +5,37 @@
   "cases": [
     {
       "id": "positive-meeting-rerender",
-      "prompt": "이 회의록을 요약하고 같은 내용을 action_items 형식으로 다시 렌더링해줘.",
+      "prompt": "$briefprint summarize these meeting notes into a cached briefing, then rerender the same content as action_items.",
       "expected_invocation": true,
       "observed_invocation": null,
       "host": null,
       "model": null,
       "date": null,
-      "notes": "Expected to invoke because the user supplies document-like content and asks for reusable briefing/rerendering."
+      "notes": "Expected to invoke because the user explicitly invokes $briefprint and asks for reusable briefing/rerendering."
     },
     {
       "id": "positive-json-digest",
-      "prompt": "이 JSON payload를 임원용 digest로 만들고, 다음 요청에서 재사용할 수 있게 캐시해줘.",
+      "prompt": "$briefprint summarize this JSON payload into a cached digest for reuse in later requests.",
       "expected_invocation": true,
       "observed_invocation": null,
       "host": null,
       "model": null,
       "date": null,
-      "notes": "Expected to invoke because the user asks for cached structured briefing from supplied JSON."
+      "notes": "Expected to invoke because the user explicitly invokes $briefprint for cached structured briefing from supplied JSON."
+    },
+    {
+      "id": "negative-ordinary-summary",
+      "prompt": "Summarize these meeting notes and extract action items.",
+      "expected_invocation": false,
+      "observed_invocation": null,
+      "host": null,
+      "model": null,
+      "date": null,
+      "notes": "Expected not to invoke because this is an ordinary one-off summary without explicit briefprint invocation."
     },
     {
       "id": "negative-live-news",
-      "prompt": "오늘 최신 금융 뉴스를 찾아서 분석해줘.",
+      "prompt": "Find and analyze today's latest financial news.",
       "expected_invocation": false,
       "observed_invocation": null,
       "host": null,
@@ -35,7 +45,7 @@
     },
     {
       "id": "negative-source-debugging",
-      "prompt": "이 Python stack trace를 보고 버그 원인을 찾아 고쳐줘.",
+      "prompt": "Read this Python stack trace and find the root cause.",
       "expected_invocation": false,
       "observed_invocation": null,
       "host": null,

diff --git a/evals/trigger_eval_cases.json b/evals/trigger_eval_cases.json
@@ -1,10 +1,10 @@
 {
   "schema_version": "1.0.0",
-  "description": "Skill trigger and boundary fixtures only; no pipeline execution.",
+  "description": "Skill trigger and boundary fixtures only; no pipeline execution. Briefprint is explicit-use: positive cases require explicit briefprint invocation.",
   "cases": [
     {
-      "id": "pos-meeting-brief-inline",
-      "prompt": "Summarize these meeting notes and extract action items.",
+      "id": "pos-explicit-meeting-brief-inline",
+      "prompt": "$briefprint summarize these meeting notes into a cached briefing and extract action items.",
       "input": {
         "kind": "inline_document",
         "doc_type": "meeting_notes",
@@ -17,8 +17,8 @@
       }
     },
     {
-      "id": "pos-json-digest",
-      "prompt": "이 JSON payload를 임원용 digest로 바꿔줘.",
+      "id": "pos-explicit-json-digest",
+      "prompt": "$briefprint summarize this JSON payload into a reusable digest.",
       "input": {
         "kind": "inline_document",
         "doc_type": "api_payload",
@@ -31,8 +31,8 @@
       }
     },
     {
-      "id": "pos-template-rerender",
-      "prompt": "같은 문서를 action_items 형식으로 재렌더링해줘.",
+      "id": "pos-cached-state-rerender",
+      "prompt": "$briefprint rerender this cached briefing as action_items.",
       "input": {
         "kind": "cached_state"
       },
@@ -42,8 +42,8 @@
       }
     },
     {
-      "id": "pos-review-comments-document",
-      "prompt": "이 PR 리뷰 코멘트 묶음을 요약하고 남은 액션만 정리해줘.",
+      "id": "pos-explicit-review-comments-document",
+      "prompt": "Use $briefprint on these exported PR review comments and summarize actions, risks, and decisions.",
       "input": {
         "kind": "inline_document",
         "doc_type": "review_comments",
@@ -55,9 +55,23 @@
         "intent": "summarize_review_comments"
       }
     },
+    {
+      "id": "neg-ordinary-one-off-summary",
+      "prompt": "Summarize these meeting notes and extract action items.",
+      "input": {
+        "kind": "inline_document",
+        "doc_type": "meeting_notes",
+        "content_format": "markdown",
+        "sample": "Decision: ship. Action: Backend should patch PAY-482 by 2026-05-10."
+      },
+      "expect": {
+        "invoke": false,
+        "boundary": "ordinary_one_off_summary"
+      }
+    },
     {
       "id": "neg-live-research",
-      "prompt": "오늘 최신 금융 뉴스를 찾아서 분석해줘.",
+      "prompt": "Find and analyze today's latest financial news.",
       "input": {
         "kind": "no_document"
       },
@@ -79,7 +93,7 @@
     },
     {
       "id": "neg-debugging",
-      "prompt": "이 stack trace 원인을 디버깅하고 수정 방법을 알려줘.",
+      "prompt": "Debug this stack trace and tell me how to fix it.",
       "input": {
         "kind": "stack_trace"
       },
@@ -90,7 +104,7 @@
     },
     {
       "id": "neg-translation-only",
-      "prompt": "이 문장을 영어로 번역만 해줘.",
+      "prompt": "Translate this paragraph to English only.",
       "input": {
         "kind": "plain_text"
       },
@@ -101,7 +115,7 @@
     },
     {
       "id": "neg-simple-qa",
-      "prompt": "캐시는 보통 어디에 저장돼?",
+      "prompt": "Where is the cache usually stored?",
       "input": {
         "kind": "no_document"
       },

diff --git a/references/best-practices.md b/references/best-practices.md
@@ -33,11 +33,13 @@ Provider prompt caching can reduce repeated prefix cost, but it is not the same
 A good skill should be easy to inspect:
 
 - short `SKILL.md`,
-- clear trigger phrases,
+- clear invocation examples and boundaries,
 - minimal scripts,
 - concrete schemas,
 - tests that prove behavior.
 
+The skill bundle is static install-time guidance. Briefprint's runtime cache lives under `--cache-dir`; it is created by the CLI/runtime, not by the installed skill bundle. Installing, updating, or removing the agent skill does not migrate, prune, or delete runtime caches. No portable agent-skill host contract currently provides automatic eviction for generated document state. Do not write document caches into the installed skill directory.
+
 ## 8. Validate with real samples
 
 Create a small evaluation set from actual documents and track:
@@ -85,4 +87,4 @@ Document titles, sources, summaries, actions, and risk text may contain raw HTML
 
 ## 11. Prepare short deployment descriptions
 
-Codex/OpenAI skill metadata can use a detailed `SKILL.md` description for precise triggering. Claude.ai upload flows may require a shorter description, so keep a 200-character-safe variant ready for packaging.
+Codex/OpenAI skill metadata can use a detailed `SKILL.md` description for discoverability and manual invocation guidance. Claude.ai upload flows may require a shorter description, so keep a 200-character-safe variant ready for packaging.