context-loader 1.1.0__tar.gz → 1.3.0__tar.gz

{context_loader-1.1.0 → context_loader-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: context-loader
-Version: 1.1.0
+Version: 1.3.0
 Summary: Render deterministic local Git context for any executor
 License:                                  Apache License
                                     Version 2.0, January 2004
@@ -219,15 +219,14 @@ Python standard library.
 
 ## Open-source quick start
 
-Context Loader is a local CLI that exports repository context deterministically for coding-agent workflows,
-rendering stable Markdown or JSON output.
+Current stable release: **1.3.0**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
 
 ```bash
-uv tool install context-loader
+uv tool install 'context-loader==1.3.0'
 ```
 
 ```bash
-pip install context-loader
+pip install 'context-loader==1.3.0'
 ```
 
 ```bash
@@ -240,21 +239,21 @@ project-context --repo /path/to/repo --format json
 
 ## Install
 
-Source version: `1.1.0`. Install its matching published release or an exact source commit.
+Source version: `1.3.0`. Install its matching published release or an exact source commit.
 
 Install via `uv`:
 
 ```bash
-uv tool install context-loader
+uv tool install 'context-loader==1.3.0'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install context-loader
+pip install 'context-loader==1.3.0'
 ```
 
-For development or source-based installs tracking current repository (`1.1.0`):
+For development or source-based installs tracking current repository (`1.3.0`):
 
 ```bash
 uv tool install git+https://github.com/xuanheng-tech/context-loader.git
@@ -265,8 +264,8 @@ The repository also retains `./project-context` as a direct development entry po
 ### Distributions
 
 The sole distribution is **`context-loader`**, containing the `context_loader` runtime
-and the `project-context` console script. Version `1.0.0` breaks the CLI name and Markdown
-heading contract. The JSON schema is unchanged. Terminal and any executor call this same
+and the `project-context` console script. Version `1.0.0` broke the CLI name and Markdown
+heading contract while leaving the then-current JSON schema unchanged. Terminal and any executor call this same
 entry point with explicit repository and focus arguments; no provider adapter or private
 session state is involved.
 
@@ -305,16 +304,17 @@ project-context --version
 project-context --repo /home/user/projects/example
 project-context --repo /home/user/projects/example --format markdown
 project-context --repo /home/user/projects/example --format json
+project-context --repo /home/user/projects/example --format json-compact
 project-context --repo /home/user/projects/example \
   --focus "Authentication and session management" \
   --path auth/session.py
 ```
 
 `--format` defaults to `markdown`. In Markdown mode, `--repo` retains the 0.1.1 contract: it must be
-the absolute, canonical root of a non-bare Git working tree. In JSON mode, an absolute existing
-directory inside the working tree is accepted; symlinks are normalized and the discovered root is
-reported as `canonical_root`. Relative paths, non-Git directories, regular files, and bare
-repositories are rejected in both modes.
+the absolute, canonical root of a non-bare Git working tree. In the `json` and `json-compact` modes,
+an absolute existing directory inside the working tree is accepted; symlinks are normalized and the
+discovered root is reported as `canonical_root`. Relative paths, non-Git directories, regular files,
+and bare repositories are rejected in every mode.
 
 `--focus` and `--path` are optional, bounded selection signals for the root `AGENTS.md`. `--path`
 must be repository-relative. The collector does not retain either input in output or audit data.
@@ -337,15 +337,17 @@ The output has no generated timestamp, AI summary, architecture inference, or di
 
 ## JSON Output
 
-`--format json` writes exactly one compact UTF-8 JSON document plus one trailing newline to stdout.
-Keys are serialized in sorted order with `ensure_ascii=False`. The declared contract is:
+`--format json` writes exactly one separator-compact UTF-8 JSON document plus one trailing newline
+to stdout. Keys are serialized in sorted order with `ensure_ascii=False`. `--format json-compact`
+uses the identical serialization; only the field set differs, as described under “Compact model
+consumption”. The declared contract for `--format json` is:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 3,
   "tool": {
     "name": "context-loader",
-    "version": "1.1.0"
+    "version": "1.3.0"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -375,24 +377,78 @@ Keys are serialized in sorted order with `ensure_ascii=False`. The declared cont
   "context": "the same assembled Markdown context",
   "context_sha256": "sha256-hex",
   "statuses": [],
+  "nested_context": {
+    "files": ["docs/AGENTS.md"],
+    "list_truncated": false,
+    "scan_truncated": false
+  },
   "warnings": []
 }
 ```
 
 `context_sha256` hashes the UTF-8 bytes of `context`; each `content_sha256` does the same for that
-source's `content`. `sources` contains only file bodies that actually enter the final context, in
-assembly order, after the existing newline normalization and truncation rules. `scope` distinguishes
-`repository` from `global`; version 1.0.0's fixed root-file selection currently emits only
-`repository` sources and does not add any global-file discovery.
+source's `content` body as rendered (after newline normalization, any `AGENTS.md` section selection
+and any truncation marker) — never for the raw bytes of the file at `path`, which match only for
+unselected, untruncated LF files. `sources` contains only file bodies that actually enter the final
+context, in assembly order, after the existing newline normalization and truncation rules. `scope`
+distinguishes `repository` from `global`; version 1.0.0's fixed root-file selection currently emits
+only `repository` sources and does not add any global-file discovery.
 
-`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, and truncated working-tree or declared-command listings. Each entry has stable `code`, `subject_kind`, and `subject` fields. `sources`, `context`, and `schema_version` remain unchanged; callers can ignore `statuses` safely.
+`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown — plus the nested-context truncation flags, which exist only in machine form: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, truncated working-tree or declared-command listings, and truncated nested-`AGENTS.md` presence reports. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two `nested_agents_*` codes mirror the `nested_context` truncation booleans for consumers that branch only on `statuses`; the full `nested_context` object remains a first-class field, never folded into `statuses`. Callers can ignore `statuses` safely.
 
 The optional `selection` object is present only on a rendered `AGENTS.md` source. Its section entries
 contain heading, heading level, and fixed selection reasons; it never contains the original focus or
-target path. Existing source fields and schema version 1 remain unchanged.
-
-The JSON schema version and package version are independent: `schema_version` is currently the
-integer `1`, while `tool.version` is `1.1.0`. Callers must depend only on fields declared above.
+target path. Existing per-source fields remain unchanged; the document's exact key
+set (now including `nested_context`) is named by its `schema_version`, described below.
+
+`nested_context` is always present and existence-only: `files` lists repository-relative paths of
+non-directory `AGENTS.md` entries under subdirectories, found by a bounded scan that enumerates
+directory entries, never opens or reads a candidate file and never traverses a symlink; it carries
+no sizes, no mtimes and no contents. A symlinked (even dangling) `AGENTS.md` is listed, because its
+existence comes from the directory entry itself; the scan never resolves what it points at. Any
+`.git`, `.venv`, `venv`, `node_modules` or `site-packages` directory is skipped at every depth:
+package-manager and interpreter-managed trees are not authored repository instructions.
+`list_truncated` means more matching entries exist beyond the report caps (32 paths and 4 KiB of
+path bytes); `scan_truncated` means the depth (4) or directory-count (2,000) budget was reached, or
+a directory or entry could not be read, so absence of a path is not proof of absence of the file.
+Paths are sanitized with the same escaping the Markdown uses for repository-derived text, so the
+document is always valid UTF-8. The corresponding
+`nested_agents_list_truncated` and `nested_agents_scan_truncated` status entries mirror both flags.
+Presence is not instruction: whether a nested file applies, and its text, remain the caller's
+judgment; Markdown output is unchanged.
+
+### Compact model consumption (`--format json-compact`)
+
+`--format json-compact` emits a `schema_version` 4 document: exactly the version-3 document with
+`sources[*].content` omitted. Every other field — `context`, `context_sha256`, `statuses`,
+`nested_context`, `warnings`, `tool`, `repository`, and each source's `ordinal`, `kind`, `scope`,
+`path`, `content_sha256` and optional `selection` — is identical to `--format json` for the same
+arguments.
+`sources` is provenance and index metadata, not the place a body must be fetched from: every omitted
+body is already inside `context` verbatim, so consumers should read `context` for rule text and
+reopen a source file only when the rendered body was truncated or selected away — never to recover a
+body that the document already carried.
+The projection exists because the selected source bodies already occur verbatim inside `context`,
+so carrying them again in `sources` duplicates a large share of the document bytes (measured up to
+~44% on real worktrees, scaling with how much of `context` those bodies occupy) for a model
+consumer without adding information. Nothing is lost: each omitted body remains inside `context`,
+`content_sha256` still fingerprints that rendered body, and `path` plus `canonical_root` locate the
+underlying file for a bounded manual re-read (whose raw bytes may differ from the rendered body as
+defined above). `schema_version` is an exact document selector, not an upgrade marker: version 4 is
+a field-set projection of version 3, so consumers must branch on the value and must not apply
+`>=`-superset reasoning. Introducing this compact format does
+not otherwise change default Markdown bytes, exit codes or determinism.
+
+One historical exception is acknowledged: releases 1.0.0 and 1.1.0 both emitted `schema_version` 1
+although 1.1.0 added the top-level `statuses` key. From release 1.2.0 onward each emitted number
+names exactly one key set, and the `nested_context` renumber below enforces that rule going forward.
+
+The JSON schema version and package version are independent: this build emits `schema_version` `3`
+for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.0`. Version 1
+and 2 are the exact shapes already published in release 1.2.0 and are never reused: because
+`nested_context` changes the default document's key set, version 3 names the current full-document
+key set and version 4 names the compact projection.
+Callers must depend only on fields declared above.
 The document contains no generated time or random identifier, so unchanged input produces identical
 JSON bytes. On failure, stdout remains empty and stderr contains only a short diagnostic.
 
@@ -406,7 +462,9 @@ Resolving an instruction hierarchy stays with the calling agent harness. That in
 shared or user-level instruction file outside the repository, nested or scoped `AGENTS.md` files
 under subdirectories, and any include or import directive written inside an instruction file:
 such a directive is transported as literal text and is never followed. `--path` selects sections
-of the repository-root `AGENTS.md` only; it never changes which files are read.
+of the repository-root `AGENTS.md` only; it never changes which files are read. The JSON-only
+`nested_context` field reports the existence of nested `AGENTS.md` paths without reading them;
+deciding whether any of them applies stays with the calling agent harness exactly as before.
 
 A successful run therefore proves that the bounded root context was collected and rendered. It
 does not prove that every instruction applicable to a task has been loaded.
@@ -447,6 +505,8 @@ scan that ends before EOF still reports the characters it could not select.
 - All entry-file bodies: 24 KiB
 - Declared commands: 8 KiB
 - Directory tree: 12 KiB, 300 entries, and depth 2
+- Nested `AGENTS.md` presence scan: depth 4, 2,000 directories, and at most 32 reported paths;
+  file contents are never read
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
 - Git subprocess output: 16 MiB (bounded while reading)
@@ -485,7 +545,8 @@ or candidate-file content.
 
 ## Not Included
 
-Version 1.0.0 does not provide AI summaries, project-type detection, nested `AGENTS.md` handling,
+Version 1.3.0 does not provide AI summaries, project-type detection, loading or transport of
+nested `AGENTS.md` contents (the JSON `nested_context` field reports bounded existence only),
 Memory retrieval, semantic ranking, ignore-rule parsing, plugins, profiles, caches, databases,
 network services, MCP, daemons, GUIs, CI/CD, telemetry, or automatic updates.
 
@@ -499,9 +560,13 @@ just check
 
 ## Version maintenance
 
-The versions in `pyproject.toml` and `context_loader/__init__.py`, the matching `CHANGELOG.md`
-section, and required tests must change in the same release-preparation batch. `CHANGELOG.md` is the
-authoritative version-change record. Merging to `master` is not a release; formal publication
+The versions in `pyproject.toml` and `context_loader/__init__.py`, the `tool_version` in
+`tool_cli_contract.json`, the matching `CHANGELOG.md` section, required tests, and the README
+current-stable declaration plus `context-loader==X.Y.Z`
+install pins must change in the same release-preparation batch. `CHANGELOG.md` is the
+authoritative version-change record. `scripts/release.py` rejects README stable/install
+pins that disagree with the intended package version; historical changelog entries are
+not part of that check. Merging to `master` is not a release; formal publication
 still requires a separately created and pushed tag.
 
 ## Release closure and retries

{context_loader-1.1.0 → context_loader-1.3.0}/README.md

@@ -8,15 +8,14 @@ Python standard library.
 
 ## Open-source quick start
 
-Context Loader is a local CLI that exports repository context deterministically for coding-agent workflows,
-rendering stable Markdown or JSON output.
+Current stable release: **1.3.0**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
 
 ```bash
-uv tool install context-loader
+uv tool install 'context-loader==1.3.0'
 ```
 
 ```bash
-pip install context-loader
+pip install 'context-loader==1.3.0'
 ```
 
 ```bash
@@ -29,21 +28,21 @@ project-context --repo /path/to/repo --format json
 
 ## Install
 
-Source version: `1.1.0`. Install its matching published release or an exact source commit.
+Source version: `1.3.0`. Install its matching published release or an exact source commit.
 
 Install via `uv`:
 
 ```bash
-uv tool install context-loader
+uv tool install 'context-loader==1.3.0'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install context-loader
+pip install 'context-loader==1.3.0'
 ```
 
-For development or source-based installs tracking current repository (`1.1.0`):
+For development or source-based installs tracking current repository (`1.3.0`):
 
 ```bash
 uv tool install git+https://github.com/xuanheng-tech/context-loader.git
@@ -54,8 +53,8 @@ The repository also retains `./project-context` as a direct development entry po
 ### Distributions
 
 The sole distribution is **`context-loader`**, containing the `context_loader` runtime
-and the `project-context` console script. Version `1.0.0` breaks the CLI name and Markdown
-heading contract. The JSON schema is unchanged. Terminal and any executor call this same
+and the `project-context` console script. Version `1.0.0` broke the CLI name and Markdown
+heading contract while leaving the then-current JSON schema unchanged. Terminal and any executor call this same
 entry point with explicit repository and focus arguments; no provider adapter or private
 session state is involved.
 
@@ -94,16 +93,17 @@ project-context --version
 project-context --repo /home/user/projects/example
 project-context --repo /home/user/projects/example --format markdown
 project-context --repo /home/user/projects/example --format json
+project-context --repo /home/user/projects/example --format json-compact
 project-context --repo /home/user/projects/example \
   --focus "Authentication and session management" \
   --path auth/session.py
 ```
 
 `--format` defaults to `markdown`. In Markdown mode, `--repo` retains the 0.1.1 contract: it must be
-the absolute, canonical root of a non-bare Git working tree. In JSON mode, an absolute existing
-directory inside the working tree is accepted; symlinks are normalized and the discovered root is
-reported as `canonical_root`. Relative paths, non-Git directories, regular files, and bare
-repositories are rejected in both modes.
+the absolute, canonical root of a non-bare Git working tree. In the `json` and `json-compact` modes,
+an absolute existing directory inside the working tree is accepted; symlinks are normalized and the
+discovered root is reported as `canonical_root`. Relative paths, non-Git directories, regular files,
+and bare repositories are rejected in every mode.
 
 `--focus` and `--path` are optional, bounded selection signals for the root `AGENTS.md`. `--path`
 must be repository-relative. The collector does not retain either input in output or audit data.
@@ -126,15 +126,17 @@ The output has no generated timestamp, AI summary, architecture inference, or di
 
 ## JSON Output
 
-`--format json` writes exactly one compact UTF-8 JSON document plus one trailing newline to stdout.
-Keys are serialized in sorted order with `ensure_ascii=False`. The declared contract is:
+`--format json` writes exactly one separator-compact UTF-8 JSON document plus one trailing newline
+to stdout. Keys are serialized in sorted order with `ensure_ascii=False`. `--format json-compact`
+uses the identical serialization; only the field set differs, as described under “Compact model
+consumption”. The declared contract for `--format json` is:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 3,
   "tool": {
     "name": "context-loader",
-    "version": "1.1.0"
+    "version": "1.3.0"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -164,24 +166,78 @@ Keys are serialized in sorted order with `ensure_ascii=False`. The declared cont
   "context": "the same assembled Markdown context",
   "context_sha256": "sha256-hex",
   "statuses": [],
+  "nested_context": {
+    "files": ["docs/AGENTS.md"],
+    "list_truncated": false,
+    "scan_truncated": false
+  },
   "warnings": []
 }
 ```
 
 `context_sha256` hashes the UTF-8 bytes of `context`; each `content_sha256` does the same for that
-source's `content`. `sources` contains only file bodies that actually enter the final context, in
-assembly order, after the existing newline normalization and truncation rules. `scope` distinguishes
-`repository` from `global`; version 1.0.0's fixed root-file selection currently emits only
-`repository` sources and does not add any global-file discovery.
+source's `content` body as rendered (after newline normalization, any `AGENTS.md` section selection
+and any truncation marker) — never for the raw bytes of the file at `path`, which match only for
+unselected, untruncated LF files. `sources` contains only file bodies that actually enter the final
+context, in assembly order, after the existing newline normalization and truncation rules. `scope`
+distinguishes `repository` from `global`; version 1.0.0's fixed root-file selection currently emits
+only `repository` sources and does not add any global-file discovery.
 
-`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, and truncated working-tree or declared-command listings. Each entry has stable `code`, `subject_kind`, and `subject` fields. `sources`, `context`, and `schema_version` remain unchanged; callers can ignore `statuses` safely.
+`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown — plus the nested-context truncation flags, which exist only in machine form: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, truncated working-tree or declared-command listings, and truncated nested-`AGENTS.md` presence reports. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two `nested_agents_*` codes mirror the `nested_context` truncation booleans for consumers that branch only on `statuses`; the full `nested_context` object remains a first-class field, never folded into `statuses`. Callers can ignore `statuses` safely.
 
 The optional `selection` object is present only on a rendered `AGENTS.md` source. Its section entries
 contain heading, heading level, and fixed selection reasons; it never contains the original focus or
-target path. Existing source fields and schema version 1 remain unchanged.
-
-The JSON schema version and package version are independent: `schema_version` is currently the
-integer `1`, while `tool.version` is `1.1.0`. Callers must depend only on fields declared above.
+target path. Existing per-source fields remain unchanged; the document's exact key
+set (now including `nested_context`) is named by its `schema_version`, described below.
+
+`nested_context` is always present and existence-only: `files` lists repository-relative paths of
+non-directory `AGENTS.md` entries under subdirectories, found by a bounded scan that enumerates
+directory entries, never opens or reads a candidate file and never traverses a symlink; it carries
+no sizes, no mtimes and no contents. A symlinked (even dangling) `AGENTS.md` is listed, because its
+existence comes from the directory entry itself; the scan never resolves what it points at. Any
+`.git`, `.venv`, `venv`, `node_modules` or `site-packages` directory is skipped at every depth:
+package-manager and interpreter-managed trees are not authored repository instructions.
+`list_truncated` means more matching entries exist beyond the report caps (32 paths and 4 KiB of
+path bytes); `scan_truncated` means the depth (4) or directory-count (2,000) budget was reached, or
+a directory or entry could not be read, so absence of a path is not proof of absence of the file.
+Paths are sanitized with the same escaping the Markdown uses for repository-derived text, so the
+document is always valid UTF-8. The corresponding
+`nested_agents_list_truncated` and `nested_agents_scan_truncated` status entries mirror both flags.
+Presence is not instruction: whether a nested file applies, and its text, remain the caller's
+judgment; Markdown output is unchanged.
+
+### Compact model consumption (`--format json-compact`)
+
+`--format json-compact` emits a `schema_version` 4 document: exactly the version-3 document with
+`sources[*].content` omitted. Every other field — `context`, `context_sha256`, `statuses`,
+`nested_context`, `warnings`, `tool`, `repository`, and each source's `ordinal`, `kind`, `scope`,
+`path`, `content_sha256` and optional `selection` — is identical to `--format json` for the same
+arguments.
+`sources` is provenance and index metadata, not the place a body must be fetched from: every omitted
+body is already inside `context` verbatim, so consumers should read `context` for rule text and
+reopen a source file only when the rendered body was truncated or selected away — never to recover a
+body that the document already carried.
+The projection exists because the selected source bodies already occur verbatim inside `context`,
+so carrying them again in `sources` duplicates a large share of the document bytes (measured up to
+~44% on real worktrees, scaling with how much of `context` those bodies occupy) for a model
+consumer without adding information. Nothing is lost: each omitted body remains inside `context`,
+`content_sha256` still fingerprints that rendered body, and `path` plus `canonical_root` locate the
+underlying file for a bounded manual re-read (whose raw bytes may differ from the rendered body as
+defined above). `schema_version` is an exact document selector, not an upgrade marker: version 4 is
+a field-set projection of version 3, so consumers must branch on the value and must not apply
+`>=`-superset reasoning. Introducing this compact format does
+not otherwise change default Markdown bytes, exit codes or determinism.
+
+One historical exception is acknowledged: releases 1.0.0 and 1.1.0 both emitted `schema_version` 1
+although 1.1.0 added the top-level `statuses` key. From release 1.2.0 onward each emitted number
+names exactly one key set, and the `nested_context` renumber below enforces that rule going forward.
+
+The JSON schema version and package version are independent: this build emits `schema_version` `3`
+for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.0`. Version 1
+and 2 are the exact shapes already published in release 1.2.0 and are never reused: because
+`nested_context` changes the default document's key set, version 3 names the current full-document
+key set and version 4 names the compact projection.
+Callers must depend only on fields declared above.
 The document contains no generated time or random identifier, so unchanged input produces identical
 JSON bytes. On failure, stdout remains empty and stderr contains only a short diagnostic.
 
@@ -195,7 +251,9 @@ Resolving an instruction hierarchy stays with the calling agent harness. That in
 shared or user-level instruction file outside the repository, nested or scoped `AGENTS.md` files
 under subdirectories, and any include or import directive written inside an instruction file:
 such a directive is transported as literal text and is never followed. `--path` selects sections
-of the repository-root `AGENTS.md` only; it never changes which files are read.
+of the repository-root `AGENTS.md` only; it never changes which files are read. The JSON-only
+`nested_context` field reports the existence of nested `AGENTS.md` paths without reading them;
+deciding whether any of them applies stays with the calling agent harness exactly as before.
 
 A successful run therefore proves that the bounded root context was collected and rendered. It
 does not prove that every instruction applicable to a task has been loaded.
@@ -236,6 +294,8 @@ scan that ends before EOF still reports the characters it could not select.
 - All entry-file bodies: 24 KiB
 - Declared commands: 8 KiB
 - Directory tree: 12 KiB, 300 entries, and depth 2
+- Nested `AGENTS.md` presence scan: depth 4, 2,000 directories, and at most 32 reported paths;
+  file contents are never read
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
 - Git subprocess output: 16 MiB (bounded while reading)
@@ -274,7 +334,8 @@ or candidate-file content.
 
 ## Not Included
 
-Version 1.0.0 does not provide AI summaries, project-type detection, nested `AGENTS.md` handling,
+Version 1.3.0 does not provide AI summaries, project-type detection, loading or transport of
+nested `AGENTS.md` contents (the JSON `nested_context` field reports bounded existence only),
 Memory retrieval, semantic ranking, ignore-rule parsing, plugins, profiles, caches, databases,
 network services, MCP, daemons, GUIs, CI/CD, telemetry, or automatic updates.
 
@@ -288,9 +349,13 @@ just check
 
 ## Version maintenance
 
-The versions in `pyproject.toml` and `context_loader/__init__.py`, the matching `CHANGELOG.md`
-section, and required tests must change in the same release-preparation batch. `CHANGELOG.md` is the
-authoritative version-change record. Merging to `master` is not a release; formal publication
+The versions in `pyproject.toml` and `context_loader/__init__.py`, the `tool_version` in
+`tool_cli_contract.json`, the matching `CHANGELOG.md` section, required tests, and the README
+current-stable declaration plus `context-loader==X.Y.Z`
+install pins must change in the same release-preparation batch. `CHANGELOG.md` is the
+authoritative version-change record. `scripts/release.py` rejects README stable/install
+pins that disagree with the intended package version; historical changelog entries are
+not part of that check. Merging to `master` is not a release; formal publication
 still requires a separately created and pushed tag.
 
 ## Release closure and retries

{context_loader-1.1.0 → context_loader-1.3.0}/context_loader/__init__.py

@@ -1,3 +1,3 @@
 """Project Context Loader."""
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"

{context_loader-1.1.0 → context_loader-1.3.0}/context_loader/application.py

@@ -20,13 +20,18 @@ from .collect import (
     AgentsSelectionAudit,
     AgentsSelectionInputError,
     CollectedFile,
+    NestedContextPresence,
     ProjectContext,
     collect_project_context,
 )
 from .git import ContextLoaderError, collect_repository
-from .render import render_markdown_with_details, rendered_source_contents
+from .render import _display, render_markdown_with_details, rendered_source_contents
 
-JSON_SCHEMA_VERSION = 1
+# Each value names one exact document shape and is never reused: 1 and 2 are the
+# shapes published in release 1.2.0, so adding the nested_context object to both
+# formats moved the default document to 3 and the compact projection to 4.
+JSON_SCHEMA_VERSION = 3
+COMPACT_JSON_SCHEMA_VERSION = 4
 TOOL_NAME = "context-loader"
 
 _STATUS_CODE_BY_MESSAGE = {
@@ -80,6 +85,7 @@ class ProjectContextResult:
     context_sha256: str
     warnings: tuple[str, ...]
     statuses: tuple[ContextStatus, ...]
+    nested_context: NestedContextPresence
 
 
 def _text_sha256(content: str) -> str:
@@ -184,11 +190,16 @@ def _build_statuses(
     for entry in project.directory_tree.entries:
         if entry.kind == "unreadable_directory":
             subject = entry.path if entry.path else "."
-            statuses.append(_status("unreadable", "tree_entry", subject))
+            statuses.append(_status("unreadable", "tree_entry", _display(subject)))
 
     for title in omitted_sections:
         statuses.append(_status("section_omitted", "section", title))
 
+    if project.nested_context.list_truncated:
+        statuses.append(_status("nested_agents_list_truncated", "nested_context", "AGENTS.md"))
+    if project.nested_context.scan_truncated:
+        statuses.append(_status("nested_agents_scan_truncated", "nested_context", "AGENTS.md"))
+
     deduped: list[ContextStatus] = []
     seen: set[tuple[str, str, str]] = set()
     for status in statuses:
@@ -238,6 +249,7 @@ def load_project_context(
         context_sha256=hashlib.sha256(rendered.output).hexdigest(),
         warnings=(),
         statuses=statuses,
+        nested_context=project.nested_context,
     )
 
 
@@ -272,24 +284,30 @@ def _status_document(status: ContextStatus) -> dict[str, object]:
     }
 
 
-def _source_document(source: ProjectContextSource) -> dict[str, object]:
+def _source_document(source: ProjectContextSource, *, include_content: bool) -> dict[str, object]:
     document: dict[str, object] = {
         "ordinal": source.ordinal,
         "kind": source.kind,
         "scope": source.scope,
         "path": os.fspath(source.path),
         "content_sha256": source.content_sha256,
-        "content": source.content,
     }
+    if include_content:
+        document["content"] = source.content
     if source.selection is not None:
         document["selection"] = _selection_document(source.selection)
     return document
 
 
-def render_json(result: ProjectContextResult) -> bytes:
-    """Serialize one result as stable UTF-8 JSON followed by exactly one newline."""
+def render_json(result: ProjectContextResult, *, compact: bool = False) -> bytes:
+    """Serialize one result as stable UTF-8 JSON followed by exactly one newline.
+
+    ``compact`` projects away the duplicated source bodies only at this
+    boundary: statuses and context were computed from the full model at load
+    time, so both documents agree on everything except ``sources[*].content``.
+    """
     document = {
-        "schema_version": result.schema_version,
+        "schema_version": (COMPACT_JSON_SCHEMA_VERSION if compact else result.schema_version),
         "tool": {
             "name": result.tool.name,
             "version": result.tool.version,
@@ -298,8 +316,17 @@ def render_json(result: ProjectContextResult) -> bytes:
             "requested_path": os.fspath(result.repository.requested_path),
             "canonical_root": os.fspath(result.repository.canonical_root),
         },
-        "sources": [_source_document(source) for source in result.sources],
+        "sources": [
+            _source_document(source, include_content=not compact) for source in result.sources
+        ],
         "statuses": [_status_document(status) for status in result.statuses],
+        "nested_context": {
+            # Filesystem names arrive undecoded (surrogate-escaped); sanitize exactly like
+            # tree/change paths so no raw byte can reach the UTF-8 document.
+            "files": [_display(path) for path in result.nested_context.files],
+            "list_truncated": result.nested_context.list_truncated,
+            "scan_truncated": result.nested_context.scan_truncated,
+        },
         "context": result.context,
         "context_sha256": result.context_sha256,
         "warnings": list(result.warnings),

{context_loader-1.1.0 → context_loader-1.3.0}/context_loader/cli.py

@@ -36,9 +36,12 @@ def _parser() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--format",
-        choices=("markdown", "json"),
+        choices=("markdown", "json", "json-compact"),
         default="markdown",
-        help="output format (default: markdown)",
+        help=(
+            "output format (default: markdown); json-compact omits the "
+            "duplicated source bodies (see README, Compact model consumption)"
+        ),
     )
     return parser
 
@@ -52,11 +55,12 @@ def main(argv: Sequence[str] | None = None) -> int:
             focus=arguments.focus,
             path=arguments.target_path,
         )
-        output = (
-            result.context.encode("utf-8")
-            if arguments.format == "markdown"
-            else render_json(result)
-        )
+        if arguments.format == "markdown":
+            output = result.context.encode("utf-8")
+        elif arguments.format == "json":
+            output = render_json(result)
+        else:
+            output = render_json(result, compact=True)
     except ContextLoaderError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return exc.exit_code

{context_loader-1.1.0 → context_loader-1.3.0}/context_loader/collect.py

@@ -26,6 +26,13 @@ DECLARED_COMMANDS_LIMIT_BYTES = 8 * 1024
 DIRECTORY_TREE_LIMIT_BYTES = 12 * 1024
 DIRECTORY_TREE_MAX_ITEMS = 300
 DIRECTORY_TREE_MAX_DEPTH = 2
+NESTED_AGENTS_MAX_DEPTH = 4
+NESTED_AGENTS_MAX_DIRECTORIES = 2_000
+NESTED_AGENTS_MAX_FILES = 32
+NESTED_AGENTS_MAX_LIST_BYTES = 4 * 1024
+NESTED_AGENTS_EXCLUDED_DIRECTORIES = frozenset(
+    {".git", ".venv", "node_modules", "site-packages", "venv"}
+)
 FILE_SCAN_LIMIT_BYTES = 16 * 1024 * 1024
 MAX_FILE_SCAN_BYTES = FILE_SCAN_LIMIT_BYTES
 TRUNCATION_MARKER = "… truncated by context-loader …"
@@ -190,6 +197,15 @@ class DirectoryTree:
     truncated: bool = False
 
 
+@dataclass(frozen=True, slots=True)
+class NestedContextPresence:
+    """Existence-only index of nested AGENTS.md files; their contents are never read."""
+
+    files: tuple[str, ...]
+    list_truncated: bool = False
+    scan_truncated: bool = False
+
+
 @dataclass(frozen=True, slots=True)
 class ProjectContext:
     instructions: CollectedFile
@@ -197,6 +213,7 @@ class ProjectContext:
     entry_files: tuple[CollectedFile, ...]
     commands: tuple[DeclaredCommand, ...]
     directory_tree: DirectoryTree
+    nested_context: NestedContextPresence
 
 
 @dataclass(frozen=True, slots=True)
@@ -975,6 +992,82 @@ def _collect_directory_tree(root: Path) -> DirectoryTree:
     return DirectoryTree(tuple(collected), truncated)
 
 
+def collect_nested_agents_presence(repository: Path) -> NestedContextPresence:
+    """List nested AGENTS.md paths under a bounded, contents-blind directory scan.
+
+    The scan reads directory entries only: it never opens a candidate file, never
+    traverses a symlink, and reports truncation honestly so presence claims stay
+    auditable. Any non-directory entry named AGENTS.md is listed, including
+    symlinked ones, because existence comes from enumeration alone; entry types
+    are never resolved beyond directory-vs-not, and contents remain the caller's
+    responsibility to read.
+    """
+    files: list[str] = []
+    reported_bytes = 0
+    state = {"list_truncated": False, "scan_truncated": False, "directories": 0}
+
+    def walk(directory_descriptor: int, prefix: str, depth: int) -> None:
+        nonlocal reported_bytes
+        if depth > NESTED_AGENTS_MAX_DEPTH or state["directories"] >= NESTED_AGENTS_MAX_DIRECTORIES:
+            state["scan_truncated"] = True
+            return
+        state["directories"] += 1
+        try:
+            with os.scandir(directory_descriptor) as iterator:
+                entries = sorted(iterator, key=lambda entry: entry.name)
+        except OSError:
+            state["scan_truncated"] = True
+            return
+        subdirectories: list[str] = []
+        for entry in entries:
+            try:
+                is_directory = entry.is_dir(follow_symlinks=False)
+            except OSError:
+                state["scan_truncated"] = True
+                continue
+            path = f"{prefix}/{entry.name}" if prefix else entry.name
+            if is_directory:
+                if entry.name not in NESTED_AGENTS_EXCLUDED_DIRECTORIES:
+                    subdirectories.append(path)
+                continue
+            if entry.name != "AGENTS.md" or not prefix:
+                continue
+            if len(files) >= NESTED_AGENTS_MAX_FILES:
+                state["list_truncated"] = True
+                continue
+            name_bytes = len(path.encode("utf-8", errors="surrogateescape"))
+            name_bytes += 1 if files else 0
+            if reported_bytes + name_bytes > NESTED_AGENTS_MAX_LIST_BYTES:
+                state["list_truncated"] = True
+                continue
+            reported_bytes += name_bytes
+            files.append(path)
+        for path in subdirectories:
+            flags = os.O_RDONLY | os.O_CLOEXEC | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0)
+            try:
+                child_descriptor = os.open(
+                    path.rsplit("/", 1)[-1], flags, dir_fd=directory_descriptor
+                )
+            except OSError:
+                state["scan_truncated"] = True
+                continue
+            try:
+                walk(child_descriptor, path, depth + 1)
+            finally:
+                os.close(child_descriptor)
+
+    flags = os.O_RDONLY | os.O_CLOEXEC | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        root_descriptor = os.open(repository, flags)
+    except OSError:
+        return NestedContextPresence((), False, True)
+    try:
+        walk(root_descriptor, "", 0)
+    finally:
+        os.close(root_descriptor)
+    return NestedContextPresence(tuple(files), state["list_truncated"], state["scan_truncated"])
+
+
 def collect_project_context(
     repository: Path,
     *,
@@ -1001,4 +1094,5 @@ def collect_project_context(
         entry_files=entry_files,
         commands=_collect_commands(entry_files),
         directory_tree=_collect_directory_tree(repository),
+        nested_context=collect_nested_agents_presence(repository),
     )

{context_loader-1.1.0 → context_loader-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "context-loader"
-version = "1.1.0"
+version = "1.3.0"
 description = "Render deterministic local Git context for any executor"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{context_loader-1.1.0 → context_loader-1.3.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "context-loader"
-version = "1.1.0"
+version = "1.3.0"
 description = "Render deterministic local Git context for any executor"
 license = { file = "LICENSE" }
 readme = "README.md"

{context_loader-1.1.0 → context_loader-1.3.0}/tool_cli_contract.json

@@ -15,6 +15,7 @@
         "repo_is_absolute_git_worktree",
         "markdown_requires_canonical_root",
         "json_accepts_path_inside_worktree",
+        "json_compact_accepts_path_inside_worktree",
         "target_path_is_repository_relative"
       ],
       "result_statuses": [
@@ -24,11 +25,12 @@
       ]
     }
   ],
-  "contract_version": 2,
+  "contract_version": 3,
   "flags": {
     "format": [
       "markdown",
-      "json"
+      "json",
+      "json-compact"
     ],
     "output": "stdout",
     "stderr": "bounded_diagnostic_only"
@@ -44,5 +46,5 @@
   ],
   "schema_version": 1,
   "tool_name": "context-loader",
-  "tool_version": "1.1.0"
+  "tool_version": "1.3.0"
 }