@ictechgy/context-guard 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes for the ContextGuard plugin are documented here.
 
 ## [Unreleased]
 
+## [0.4.7] - 2026-06-11
+
+- Added default-off experimental opt-in registry surfaces for future token-reduction lanes, preserving project-local intent without enabling runtime behavior.
+- Added dry-run checker/planner gates for context-diff compaction, visual crop/OCR metadata, learned compression safety policy, self-hosted metrics ledger previews, and local-proxy advisory metadata.
+- Hardened experimental planners with deny-by-default validation, redaction, exact fallback/receipt requirements, localhost-only proxy constraints, and claim boundaries for hosted API savings.
+- Updated README, Korean README, and GitHub Pages copy to document experimental opt-ins, non-shipped runtime boundaries, and evidence/future-PR gates.
+
 ## [0.4.6] - 2026-06-10
 
 - Hardened local cost ledger/key storage against symlink traversal, unsafe permissions, and partial writes while improving recent-ledger loading performance.

package/README.ko.md

@@ -76,7 +76,7 @@ ContextGuard는 provider 캐시, semantic cache, 프롬프트 압축 도구를
 | Provider prompt/context caching | 안정적인 프롬프트 앞부분을 재사용합니다. | 보완 관계입니다. ContextGuard는 자주 바뀌는 컨텍스트 뒷부분을 더 작고 깨끗하게 유지하도록 돕고, `context-guard-audit`로 배치를 감지하며, `context-guard cost`로 Anthropic 요청이 cache read 대신 cache write가 될 가능성을 미리 알릴 수 있습니다. |
 | Semantic response cache | 같거나 비슷한 요청의 이전 답변을 재사용합니다. | 보완 관계입니다. ContextGuard는 AI 답변 캐시를 제공하지 않습니다. |
 | 프롬프트/컨텍스트 압축 | 이미 선택된 텍스트를 더 짧게 만듭니다. | 인접한 역할입니다. ContextGuard는 로컬 출력 축약과 요약을 제공하지만, 무손실 의미 압축을 보장하지 않습니다. |
-| 실험적 learned/multimodal/self-hosted 기법 | 프롬프트를 압축하거나, 시각 자료를 줄이거나, self-hosted 추론 내부를 최적화합니다. | 품질 보존을 확인하는 matched benchmark가 통과하기 전까지는 experimental radar에만 기록하며, hosted API 절감 주장으로 보지 않습니다. |
+| 실험 dry-run planner | learned compression, visual crop/OCR, self-hosted metrics, context-diff compaction, local proxy 후보를 런타임 출시 전에 검토합니다. | 모두 기본 비활성·자문 전용입니다. 별도 evidence gate와 future PR gate 없이는 압축/OCR/프록시 런타임이나 hosted API 절감 주장으로 보지 않습니다. |
 | ContextGuard | 불필요한 파일, 로그, 반복 실패, 과도한 출력이 에이전트 컨텍스트에 들어가기 전에 줄어들도록 돕습니다. | 로컬 가드레일, 되돌릴 수 있는 로컬 보관본, 측정 도구입니다. |
 
 설계에 참고한 관련 패턴은 다음과 같습니다.
@@ -113,7 +113,7 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 - 설치만으로 전역 Claude 설정을 변경하지 않습니다.
 - 절감 수치가 필요할 때 직접 전후 비교 측정을 대신하지 않습니다.
 - 로컬 RAM/디스크 보관본은 다음에 보낼 컨텍스트를 줄이는 데 도움될 수 있지만 Anthropic provider prompt cache를 대체하거나 cache hit를 보장하지 않습니다. 배포나 청구 설명 전에는 Anthropic prompt caching/pricing 문서를 다시 확인하세요: https://docs.anthropic.com/en/build-with-claude/prompt-caching 및 https://platform.claude.com/docs/en/about-claude/pricing.
-- learned compression, multimodal OCR/crop pruning, self-hosted KV/latent inference optimization은 runtime 기능으로 제공하지 않습니다. 이 항목들은 research radar에만 기록된, 검증 게이트를 통과하지 않은 실험 항목입니다.
+- 실험 헬퍼는 dry-run 안전성 checker/planner만 제공합니다. learned-compression 정책, visual crop/OCR 메타데이터, self-hosted metrics ledger preview, context-diff compaction 계획, local-proxy 제약은 검토할 수 있지만 learned/synthetic compressor runtime·embedding·reranker·model call·replacement 생성, OCR/crop runtime·스크린샷 캡처·이미지 파싱·외부 OCR/이미지 서비스 호출, self-hosted KV/latent inference optimization runtime, 실제 proxy forwarding runtime은 제공하지 않습니다.
 - 예전 `/claude-token-optimizer:*` Claude Code 슬래시 명령을 별칭으로 제공하지 않습니다. 설치 후에는 `/context-guard:*`를 사용하세요.
 
 기존 자동화가 바로 깨지지 않도록 로컬 CLI 호환 래퍼(`claude-token-*`, `claude-read-symbol`, `claude-trim-output`, `claude-sanitize-output`)는 `bin/`에서 계속 제공합니다.
@@ -327,17 +327,45 @@ head/tail 로그 대신 의미 요약이 필요하면 `--digest markdown` 또는
 - 토큰 절감 주장은 대응 태스크 양쪽 모두에 `primary_tokens_measured`가 있을 때만 계산합니다.
 - `matched_pair_evidence`는 성공한 task bucket을 transform, 측정 가능 여부, quality gate, claim boundary와 연결하므로 절감 문구를 쓰기 전에 먼저 확인해야 합니다.
 - `wall_time_seconds`, `provider_cached_tokens`, `provider_cached_tokens_measured`는 진단용 텔레메트리이며, ContextGuard가 직접 만든 토큰·비용 절감 증거로 보지 않습니다.
-- 선택적 `self_hosted_metrics`는 run별 JSONL ledger sidecar로만 기록하고 CSV/report 요약에는 넣지 않으며, hosted API token/cost 절감 주장의 근거로 포함해서는 안 됩니다.
+- 선택적 `self_hosted_metrics`는 run별 JSONL ledger sidecar로만 기록하고 CSV/report 요약에는 넣지 않으며, hosted API token/cost 절감 주장의 근거로 포함해서는 안 됩니다. `context-guard experiments plan self-hosted-metrics-ledger`는 이런 sidecar의 dry-run preview만 만들고 ledger 파일을 쓰지 않습니다.
 - 비용 필드가 0이거나 없으면 토큰 절감만 표시하고 실제 비용 절감은 주장하지 않습니다.
 - CSV 스키마는 엄격하게 검사합니다. 벤치마크 헬퍼를 업그레이드한 뒤에는 새 `--csv` 파일을 시작하거나 mismatch 오류가 알려주는 헤더로 마이그레이션하세요.
 
 최소 보고서 형태 예시는 [`docs/benchmark-report.example.json`](docs/benchmark-report.example.json)을, 작업 유형별 합성 예시와 안전한 해석 경계는 [`docs/benchmark-workflow-examples.md`](docs/benchmark-workflow-examples.md)을, fixture-only 실험 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](docs/experimental-benchmark-fixtures.md)을 참고하세요.
 
+### 실험 기능 opt-in 관리
+
+실험 lane은 **기본 비활성**입니다. Registry는 프로젝트 로컬 의도와 메타데이터만 기록하며, `experiments enable`만으로 안정 런타임 동작이 켜지지 않습니다. 각 helper는 여전히 명시적인 실험 flag와 evidence boundary를 요구합니다.
+
+```bash
+context-guard experiments list
+context-guard experiments status --json
+context-guard experiments plan context-diff-compaction --json < change.diff
+context-guard experiments plan visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --missed-context-note "outside crop omitted"
+context-guard experiments plan learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" < sanitized-prose.txt
+context-guard experiments plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
+context-guard experiments plan local-proxy --json --bind-host 127.0.0.1 --target-host 127.0.0.1 --runtime-gate-ack
+context-guard experiments enable output-receipt-trim --root .
+context-guard experiments disable output-receipt-trim --root .
+```
+
+`--runtime-gate-ack` 예시는 advisory metadata만 만들며 forwarding을 켜지 않습니다.
+
+기본적으로 프로젝트 설정은 `.context-guard/experiments.json`에 저장됩니다. 명시적인 프로젝트 로컬 재정의가 필요할 때만 `--config <path>`를 사용하세요. 실험 메타데이터에는 risk level, gate requirement, explicit command/flag surface, claim boundary가 포함되어 provider-measured matched-task evidence 없이는 hosted API token/cost savings claim으로 쓰지 않도록 합니다. `experiments enable`은 의도만 기록하며 helper를 실행하거나 명시 flag를 대체하거나 exact receipt/re-expand evidence 없는 content replacement를 허용하지 않습니다.
+
+| Dry-run 안전성 checker/planner | 출력하는 것 | 넘지 않는 경계 |
+| --- | --- | --- |
+| `context-diff-compaction` | diff에 대한 검토용 compaction 조언. | replacement text를 emit하지 않습니다. 정확한 receipt/re-expand handle은 사람 검토나 future gated review용 메타데이터로만 기록합니다. |
+| `visual-crop-ocr` | 전체 visual evidence, crop bounds, OCR note, confidence, missed context 메타데이터. | 스크린샷 캡처, crop/OCR 런타임, 이미지 파싱, 외부 OCR/image service 호출을 하지 않습니다. |
+| `learned-compression` | sanitized trusted prose와 exact fallback receipt를 위한 deny-by-default 정책 검사. | embedding, reranker, model call, learned/synthetic compressor runtime, replacement 생성을 하지 않습니다. |
+| `self-hosted-metrics-ledger` | local/model-server latency, memory, quality, energy, throughput, local-cost metric의 읽기 전용 ledger-compatible preview. | ledger 파일을 쓰지 않으며 hosted API token/cost 절감 주장 근거로 쓰지 않습니다. |
+| `local-proxy` | 미래 local proxy 후보에 대한 localhost-only advisory metadata. | listener를 시작하지 않고, traffic을 forward하지 않으며, API key를 저장하지 않고, ledger를 쓰지 않습니다. non-local bind/target/upstream은 차단하며 실제 forwarding은 별도 future runtime gate가 필요합니다. |
+
 ## 아직 제공하지 않는 기능
 
 아래 항목은 프로젝트가 기록해 둔 방향일 뿐, 약속된 기능이 아닙니다. 저장소의 다른 문서에 명시되지 않는 한 아직 제공 기능이 아닙니다.
 
-- learned prompt/context compression, multimodal crop/OCR 또는 visual-token pruning, self-hosted KV/latent inference optimization. 자세한 내용은 [experimental token-reduction radar](research/experimental-token-reduction-radar.md)와 [fixture-only experimental benchmark starters](docs/experimental-benchmark-fixtures.md)를 참고하세요. 이 lane들은 matched successful task, failure-rate guardrail, human-correction tracking, shifted-cost accounting, provider-measured token/cost evidence가 있어야 hosted API 절감 주장을 할 수 있습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, local proxy constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
+- learned/synthetic compressor runtime, multimodal crop/OCR 또는 visual-token pruning runtime, self-hosted KV/latent inference optimization, 실제 proxy forwarding runtime. 자세한 내용은 [experimental token-reduction radar](research/experimental-token-reduction-radar.md)와 [fixture-only experimental benchmark starters](docs/experimental-benchmark-fixtures.md)를 참고하세요. 이 항목들은 later-roadmap gate를 통과하기 전까지 제공 기능이 아닙니다. matched successful task, failure-rate guardrail, human-correction tracking, shifted-cost accounting, provider가 측정한 token/cost evidence와 별도 future PR gate가 있어야 hosted API 절감 주장이나 런타임 기능 주장으로 승격할 수 있습니다.
 
 ## 저장소 구조
 

package/README.md

@@ -76,7 +76,7 @@ ContextGuard is complementary to provider and semantic caches, and adjacent to p
 | Provider prompt/context caching | Reusing stable prompt prefixes. | Complementary; ContextGuard helps keep the changing tail of context smaller and cleaner, `context-guard-audit` can flag likely volatile prefix layouts, and `context-guard cost` can warn when an Anthropic request is likely to create/cache-write instead of read. |
 | Semantic response cache | Reusing answers to identical or similar requests. | Complementary; ContextGuard does not serve cached AI answers. |
 | Prompt/context compression | Shortening text that is already selected for the model. | Adjacent; ContextGuard trims and summarizes local output, but does not promise lossless semantic compression. |
-| Experimental learned/multimodal/self-hosted techniques | Compressing prompts, reducing visual evidence, or optimizing self-hosted inference internals. | Tracked only in the experimental radar until matched benchmarks prove quality-preserving value; not a hosted API savings claim. |
+| Experimental dry-run planners | Reviewing learned-compression, visual crop/OCR, self-hosted metrics, context-diff compaction, and local-proxy ideas before any runtime path ships. | Default-off and advisory-only; no runtime compression, OCR, forwarding, or hosted-savings claim without separate evidence and future PR gates. |
 | ContextGuard | Avoiding unnecessary files, logs, repeated failures, and noisy output before they enter agent context. | Local guardrails, reversible artifacts, and measurement. |
 
 Related patterns that informed the design:
@@ -113,7 +113,7 @@ When you need a savings claim, measure it on your own tasks:
 - It does not mutate global Claude settings during install.
 - It does not replace real before/after measurement when you need a savings claim.
 - Local RAM/disk receipts can reduce what you send next, but they do **not** replace Anthropic's provider prompt cache or guarantee cache hits. Recheck Anthropic prompt-caching and pricing docs before release or billing claims: https://docs.anthropic.com/en/build-with-claude/prompt-caching and https://platform.claude.com/docs/en/about-claude/pricing.
-- It does not ship learned compression, multimodal OCR/crop pruning, or self-hosted KV/latent inference optimization as runtime features; those remain gated experiments in the research radar.
+- Experimental helpers are dry-run checker/planner surfaces only. ContextGuard can review learned-compression policy, visual crop/OCR metadata, self-hosted metrics ledger previews, context-diff compaction plans, and local-proxy constraints, but it does not ship learned/synthetic compressor runtime, embeddings, rerankers, model calls, replacement generation, OCR/crop runtime, self-hosted KV/latent inference optimization, or actual proxy forwarding runtime.
 - It does not alias the old `/claude-token-optimizer:*` Claude Code slash-command namespace. Use `/context-guard:*` after installing this plugin.
 
 Legacy local CLI wrappers (`claude-token-*`, `claude-read-symbol`, `claude-trim-output`, and `claude-sanitize-output`) still ship in `bin/` so existing automation can migrate gradually.
@@ -369,11 +369,41 @@ Read the report through its claim boundaries before writing any savings statemen
 
 See [`docs/benchmark-report.example.json`](docs/benchmark-report.example.json) for a minimal report-shape example, [`docs/benchmark-workflow-examples.md`](docs/benchmark-workflow-examples.md) for workflow-specific synthetic examples, and [`docs/experimental-benchmark-fixtures.md`](docs/experimental-benchmark-fixtures.md) for fixture-only experimental task/variant starters.
 
+### Manage experimental opt-ins
+
+Experimental lanes are **default off**. The registry records project-local intent and metadata only; enabling an experiment does not activate stable runtime behavior by itself. Later helpers must still require explicit experimental flags before using these lanes.
+
+```bash
+context-guard experiments list
+context-guard experiments status --json
+context-guard experiments plan context-diff-compaction --json < change.diff
+context-guard experiments plan visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --missed-context-note "outside crop omitted"
+context-guard experiments plan learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" < sanitized-prose.txt
+context-guard experiments plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
+context-guard experiments plan local-proxy --json --bind-host 127.0.0.1 --target-host 127.0.0.1 --runtime-gate-ack
+context-guard experiments enable output-receipt-trim --root .
+context-guard experiments disable output-receipt-trim --root .
+```
+
+The `--runtime-gate-ack` example still produces advisory metadata only; it does not enable forwarding.
+
+By default, project settings are stored in `.context-guard/experiments.json`. Use `--config <path>` only for an explicit project-local override. Experiment metadata includes risk level, gate requirements, explicit command/flag surfaces, and claim boundaries so hosted API token/cost savings are not claimed without provider-measured matched-task evidence. `experiments enable` records intent only; it does not run helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
+
+Shipped experimental dry-run checker/planner surfaces are intentionally narrow:
+
+| Planner/checker | What it emits | Hard boundary |
+| --- | --- | --- |
+| `context-diff-compaction` | Reviewable compaction advice for diffs. | Does not emit replacement text; exact receipt/re-expand handles are recorded only for human or future gated review. |
+| `visual-crop-ocr` | Metadata for full visual evidence, crop bounds, OCR notes, confidence, and missed context. | No screenshot capture, crop/OCR runtime, image parsing, or external OCR/image service. |
+| `learned-compression` | Deny-by-default policy checks for sanitized trusted prose with exact fallback receipts. | No embeddings, rerankers, model calls, learned/synthetic compressor runtime, or replacement generation. |
+| `self-hosted-metrics-ledger` | Read-only ledger-compatible previews for local/model-server latency, memory, quality, energy, throughput, and local-cost metrics. | Does not write a ledger and does not support hosted API token/cost savings claims. |
+| `local-proxy` | Localhost-only advisory metadata for a possible future local proxy. | Starts no listener, forwards no traffic, persists no API keys, writes no ledger, blocks non-local bind/target/upstream values, and requires a separate future runtime gate before any forwarding implementation. |
+
 ## What is not yet shipped
 
 These are directions the project has noted, not committed features. Nothing here ships unless documented elsewhere in the repository.
 
-- learned prompt/context compression, multimodal crop/OCR or visual-token pruning, and self-hosted KV/latent inference optimizations. See the [experimental token-reduction radar](research/experimental-token-reduction-radar.md) and [fixture-only experimental benchmark starters](docs/experimental-benchmark-fixtures.md); these lanes require matched successful tasks, failure-rate guardrails, human-correction tracking, shifted-cost accounting, and provider-measured token/cost evidence before any hosted API savings claim. The radar's later-roadmap gates also keep neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, and local proxy constraints experimental/non-shipped until a separate future PR satisfies those gates.
+- Learned/synthetic compressor runtime, multimodal crop/OCR or visual-token pruning runtime, self-hosted KV/latent inference optimization, and actual proxy forwarding runtime. See the [experimental token-reduction radar](research/experimental-token-reduction-radar.md) and [fixture-only experimental benchmark starters](docs/experimental-benchmark-fixtures.md); those lanes remain experimental/non-shipped under the later-roadmap gate until matched successful tasks, failure-rate guardrails, human-correction tracking, shifted-cost accounting, provider-measured token/cost evidence, and separate future PR gates justify any hosted API savings claim or runtime feature claim.
 
 ## Repository layout
 

package/context-guard-kit/README.md

@@ -60,6 +60,8 @@ python3 context-guard-kit/sanitize_output.py -- git diff
 
 `cost_guard.py compile`은 section manifest의 `protected`, `semantic_sensitive`, `protected_zone_classes`, `content_type`, `volatile`, `ttl`, `bytes` 필드를 읽어 `protected_zone_policy`와 `transform_policy`를 출력합니다. `protected=true`와 `volatile=true`가 같이 있으면 volatile이 cache ordering을 tail 쪽으로 보내고, protection은 transform/retrieval 정책만 제어합니다. 대용량 protected section은 local artifact retrieval을 권고하지만 provider prompt cache를 대체한다고 주장하지 않습니다.
 
+`experimental_registry.py` provides the `context-guard experiments` metadata surface. It is default-off and project-local: `enable`/`disable` update `.context-guard/experiments.json` only, while existing helper behavior still requires explicit flags. The registry marks the receipt-backed output trim path (`trim_command_output.py --digest markdown|json --artifact-receipt`) and protected-zone policy path (`context_compress.py --protected-policy`, plus `cost_guard.py compile` protected section metadata) as available explicit-flag experiments. It also exposes `experimental_registry.py plan context-diff-compaction` as a read-only dry-run planner: it summarizes diff files/hunks and reports whether user-supplied exact receipt/re-expand handles are present, but it never emits compacted replacement text or verifies receipt storage. `experimental_registry.py plan visual-crop-ocr` is similarly a shipped dry-run metadata planner for full visual evidence receipts plus crop/OCR fixture notes; it never crops images, parses screenshots, calls OCR/image services, or emits replacement evidence. `experimental_registry.py plan learned-compression` is a deny-by-default dry-run safety checker for sanitized trusted prose plus exact fallback handles; learned/synthetic compressor runtime is not shipped, and the checker never runs embeddings, model calls, rerankers, or replacement generation. `experimental_registry.py plan self-hosted-metrics-ledger` is a read-only dry-run preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost sidecar evidence; it never writes a ledger and never turns self-hosted telemetry into hosted API token/cost savings claims. `experimental_registry.py plan local-proxy` is a localhost-only dry-run advisory plan: it starts no listener, forwards no traffic, keeps no API-key material, writes no ledgers, and permits no non-local targets without a separate future runtime gate. Other roadmap lanes remain advisory until separate runtime gates exist.
+
 `benchmark_runner.py`는 `research/benchmark-plan.md`의 고정 task/variant 실험을 실행합니다. `variant_prompt_files`는 선택된 task/variant를 필터링한 뒤 필요한 file-backed prompt만 읽으므로 선택하지 않은 fixture의 누락 파일이 선택된 실행을 깨지 않습니다. `--ledger-jsonl`은 subagent·artifact 등 외부 실행 표면으로 옮겨간 token/cost와 run별 측정 가능 여부를 남기고, 선택적 `self_hosted_metrics` provider payload는 run별 sidecar로만 기록합니다. `--report-json`은 baseline 대비 실제 token/cost 절감과 proxy byte 감소를 분리한 A/B report를 생성하며, `self_hosted_metrics`는 CSV/report 요약에 접지 않습니다. Report의 `matched_pair_evidence`는 성공한 baseline/variant task bucket을 transform, quality gate, 측정 가능 여부, claim boundary와 연결하므로 절감 주장을 쓰기 전에 이 항목을 확인하세요.
 
 `../research/experimental-token-reduction-radar.md`는 learned compression, multimodal crop/OCR/visual-token pruning, self-hosted KV/latent inference optimization 같은 선택적 미래 실험을 문서화한 gate입니다. `../docs/experimental-benchmark-fixtures.md`에는 fixture-only task/variant 시작 예시가 있습니다. 이 radar와 fixture는 현재 제공되는 runtime helper가 아니며, hosted API token/cost 절감을 보장하지 않습니다. hosted API token/cost 절감 주장은 provider가 측정한 matched-task 근거가 있을 때만 허용합니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, local proxy constraint를 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 유지합니다.

package/context-guard-kit/context_escrow.py

@@ -766,10 +766,20 @@ def cap_text(text: str, max_chars: int) -> tuple[str, bool]:
     return text[:keep].rstrip() + marker, True
 
 
-def query_content(content: str, *, line_range: tuple[int, int] | None, pattern: str | None, max_lines: int) -> tuple[str, dict[str, object]]:
+def query_content(
+    content: str,
+    *,
+    line_range: tuple[int, int] | None,
+    pattern: str | None,
+    max_lines: int,
+    full: bool = False,
+) -> tuple[str, dict[str, object]]:
     lines = content.splitlines(True)
     selected: list[tuple[int, str]] = []
-    if line_range is not None:
+    if full:
+        selected = list(enumerate(lines, start=1))
+        selector = {"type": "full"}
+    elif line_range is not None:
         start, end = line_range
         selected = list(enumerate(lines[start - 1 : end], start=start))
         selector = {"type": "lines", "start": start, "end": end}
@@ -780,15 +790,18 @@ def query_content(content: str, *, line_range: tuple[int, int] | None, pattern:
         selected = list(enumerate(lines[:max_lines], start=1))
         selector = {"type": "head", "max_lines": max_lines}
     total_matches = len(selected)
-    selected = selected[:max_lines]
+    if not full:
+        selected = selected[:max_lines]
     text = "".join(line for _idx, line in selected)
     return text, {"selector": selector, "returned_lines": len(selected), "matched_lines": total_matches, "total_lines": len(lines)}
 
 
 def get_command(args: argparse.Namespace) -> int:
     artifact_id = args.artifact_id
-    max_chars = bounded_int(args.max_chars, DEFAULT_MAX_CHARS, 1, 1_000_000)
+    full = bool(getattr(args, "full", False))
     try:
+        if full and (args.lines or args.pattern or args.max_lines is not None):
+            raise ValueError("--full cannot be combined with --lines, --pattern, or --max-lines")
         last_missing: FileNotFoundError | None = None
         for directory in artifact_read_directories(args.dir):
             try:
@@ -815,12 +828,14 @@ def get_command(args: argparse.Namespace) -> int:
         actual_sha = hashlib.sha256(content.encode("utf-8", errors="replace")).hexdigest()
         if actual_sha != expected_sha:
             raise ValueError(f"artifact content checksum mismatch: {artifact_id}")
+        default_max_chars = max(DEFAULT_MAX_CHARS, expected_bytes) if full else DEFAULT_MAX_CHARS
+        max_chars = bounded_int(args.max_chars, default_max_chars, 1, MAX_MAX_BYTES)
         line_range = parse_line_range(args.lines)
         if line_range is not None and args.max_lines is None:
             max_lines = min(line_range[1] - line_range[0] + 1, MAX_QUERY_LINES)
         else:
             max_lines = bounded_int(args.max_lines, DEFAULT_MAX_LINES, 1, MAX_QUERY_LINES)
-        selected, query = query_content(content, line_range=line_range, pattern=args.pattern, max_lines=max_lines)
+        selected, query = query_content(content, line_range=line_range, pattern=args.pattern, max_lines=max_lines, full=full)
         selected, capped = cap_text(selected, max_chars)
     except (FileNotFoundError, ValueError, OSError, json.JSONDecodeError) as exc:
         print(f"context-guard-artifact: {exc}", file=sys.stderr)
@@ -895,7 +910,8 @@ def build_parser() -> argparse.ArgumentParser:
     get.add_argument("--lines", help="1-based inclusive line range, e.g. 10:40")
     get.add_argument("--pattern", help="literal substring filter")
     get.add_argument("--max-lines", type=int, default=None)
-    get.add_argument("--max-chars", type=int, default=DEFAULT_MAX_CHARS)
+    get.add_argument("--full", action="store_true", help="return full stored artifact content; cannot be combined with selectors")
+    get.add_argument("--max-chars", type=int, default=None)
     get.add_argument("--json", action="store_true", help="emit query JSON with content")
     get.set_defaults(func=get_command)
 

package/context-guard-kit/context_guard_cli.py

@@ -22,6 +22,7 @@ HELPER_SUBCOMMANDS: dict[str, tuple[str, ...]] = {
     "doctor": ("context-guard-setup", "--verify"),
     "audit": ("context-guard-audit",),
     "diet": ("context-guard-diet",),
+    "experiments": ("context-guard-experiments",),
     "scan": ("context-guard-diet", "scan"),
     "trim-output": ("context-guard-trim-output",),
     "trim": ("context-guard-trim-output",),