agent-first-data 0.14.2__tar.gz → 0.16.0__tar.gz

{agent_first_data-0.14.2 → agent_first_data-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.14.2
+Version: 0.16.0
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -14,22 +14,21 @@ pip install agent-first-data
 ```
 
 ```python
-from agent_first_data import output_json, output_plain
+from agent_first_data import json_result, output_json, output_plain
 
-value = {
-    "code": "ok",
-    "result": {
+value = json_result(
+    {
         "api_key_secret": "sk-123",
         "latency_ms": 1280,
         "db_url": "postgres://user:p@ss@db/app?token_secret=abc",
-    },
-}
+    }
+).build()
 
 print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -44,13 +43,14 @@ init_logging_json("INFO", secret_names=("authorization",))
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
 - YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
-- Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
-- `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+- Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
+- `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
 - Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+- Use `agent_first_data.stream_redirect.install_from_raw_args()` before version/help handling if a CLI exposes `--stdout-file` or `--stderr-file`; stderr is redirected as native diagnostics, not JSON.
 
 ## Reference
 
 - Full convention and API groups: [docs/overview.md](https://github.com/agentfirstkit/agent-first-data/blob/main/docs/overview.md)
 - Formal cross-language contract: [spec/agent-first-data.md](https://github.com/agentfirstkit/agent-first-data/blob/main/spec/agent-first-data.md)
 - Conformance fixtures: [spec/fixtures](https://github.com/agentfirstkit/agent-first-data/tree/main/spec/fixtures)
-- Agent skill: [skills/agent-first-data.md](https://github.com/agentfirstkit/agent-first-data/blob/main/skills/agent-first-data.md)
+- Agent skill: [skills/agent-first-data/SKILL.md](https://github.com/agentfirstkit/agent-first-data/blob/main/skills/agent-first-data/SKILL.md)

{agent_first_data-0.14.2 → agent_first_data-0.16.0}/README.md

@@ -5,22 +5,21 @@ pip install agent-first-data
 ```
 
 ```python
-from agent_first_data import output_json, output_plain
+from agent_first_data import json_result, output_json, output_plain
 
-value = {
-    "code": "ok",
-    "result": {
+value = json_result(
+    {
         "api_key_secret": "sk-123",
         "latency_ms": 1280,
         "db_url": "postgres://user:p@ss@db/app?token_secret=abc",
-    },
-}
+    }
+).build()
 
 print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -35,13 +34,14 @@ init_logging_json("INFO", secret_names=("authorization",))
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
 - YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
-- Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
-- `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+- Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
+- `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
 - Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+- Use `agent_first_data.stream_redirect.install_from_raw_args()` before version/help handling if a CLI exposes `--stdout-file` or `--stderr-file`; stderr is redirected as native diagnostics, not JSON.
 
 ## Reference
 
 - Full convention and API groups: [docs/overview.md](https://github.com/agentfirstkit/agent-first-data/blob/main/docs/overview.md)
 - Formal cross-language contract: [spec/agent-first-data.md](https://github.com/agentfirstkit/agent-first-data/blob/main/spec/agent-first-data.md)
 - Conformance fixtures: [spec/fixtures](https://github.com/agentfirstkit/agent-first-data/tree/main/spec/fixtures)
-- Agent skill: [skills/agent-first-data.md](https://github.com/agentfirstkit/agent-first-data/blob/main/skills/agent-first-data.md)
+- Agent skill: [skills/agent-first-data/SKILL.md](https://github.com/agentfirstkit/agent-first-data/blob/main/skills/agent-first-data/SKILL.md)

agent_first_data-0.16.0/agent_first_data/__init__.py

@@ -0,0 +1,92 @@
+"""Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates."""
+
+from agent_first_data.format import (
+    LogLevel,
+    Event,
+    EventBuildError,
+    json_result,
+    json_error,
+    json_progress,
+    json_log,
+    ResultBuilder,
+    ErrorBuilder,
+    ProgressBuilder,
+    LogBuilder,
+    validate_protocol_event,
+    validate_protocol_stream,
+    EventDecodeError,
+    DecodedResult,
+    DecodedError,
+    DecodedProgress,
+    DecodedLog,
+    decode_protocol_event,
+    RedactionPolicy,
+    OutputStyle,
+    OutputOptions,
+    output_json,
+    output_yaml,
+    output_plain,
+    redacted_value,
+    redact_url_secrets,
+    parse_size,
+    normalize_utc_offset,
+    is_valid_rfc3339_date,
+    is_valid_rfc3339_time,
+)
+
+from agent_first_data.cli import (
+    OutputFormat,
+    LogFilters,
+    CliEmitter,
+    cli_parse_output,
+    cli_parse_log_filters,
+    cli_output,
+    build_cli_error,
+    build_cli_version,
+    cli_render_version,
+    cli_handle_version_or_continue,
+)
+
+__all__ = [
+    "LogLevel",
+    "Event",
+    "EventBuildError",
+    "json_result",
+    "json_error",
+    "json_progress",
+    "json_log",
+    "ResultBuilder",
+    "ErrorBuilder",
+    "ProgressBuilder",
+    "LogBuilder",
+    "validate_protocol_event",
+    "validate_protocol_stream",
+    "EventDecodeError",
+    "DecodedResult",
+    "DecodedError",
+    "DecodedProgress",
+    "DecodedLog",
+    "decode_protocol_event",
+    "RedactionPolicy",
+    "OutputStyle",
+    "OutputOptions",
+    "output_json",
+    "output_yaml",
+    "output_plain",
+    "redacted_value",
+    "redact_url_secrets",
+    "parse_size",
+    "normalize_utc_offset",
+    "is_valid_rfc3339_date",
+    "is_valid_rfc3339_time",
+    "OutputFormat",
+    "LogFilters",
+    "CliEmitter",
+    "cli_parse_output",
+    "cli_parse_log_filters",
+    "cli_output",
+    "build_cli_error",
+    "build_cli_version",
+    "cli_render_version",
+    "cli_handle_version_or_continue",
+]

agent_first_data-0.16.0/agent_first_data/assets/protocol-v1.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentfirstkit.org/schemas/agent-first-data/protocol-v1.schema.json",
+  "title": "Agent-First Data Protocol v1 Event",
+  "type": "object",
+  "oneOf": [
+    {"$ref": "#/$defs/resultEvent"},
+    {"$ref": "#/$defs/errorEvent"},
+    {"$ref": "#/$defs/progressEvent"},
+    {"$ref": "#/$defs/logEvent"}
+  ],
+  "$defs": {
+    "trace": {
+      "type": "object"
+    },
+    "resultEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {"const": "result"},
+        "result": true,
+        "trace": {"$ref": "#/$defs/trace"}
+      },
+      "required": ["kind", "result"],
+      "additionalProperties": false
+    },
+    "errorEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {"const": "error"},
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {"type": "string", "minLength": 1},
+            "message": {"type": "string", "minLength": 1},
+            "retryable": {"type": "boolean"},
+            "hint": {"type": "string"}
+          },
+          "required": ["code", "message", "retryable"],
+          "additionalProperties": true
+        },
+        "trace": {"$ref": "#/$defs/trace"}
+      },
+      "required": ["kind", "error"],
+      "additionalProperties": false
+    },
+    "progressEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {"const": "progress"},
+        "progress": {
+          "type": "object",
+          "properties": {
+            "message": {"type": "string", "minLength": 1}
+          },
+          "additionalProperties": true
+        },
+        "trace": {"$ref": "#/$defs/trace"}
+      },
+      "required": ["kind", "progress"],
+      "additionalProperties": false
+    },
+    "logEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {"const": "log"},
+        "log": {
+          "type": "object",
+          "properties": {
+            "message": {"type": "string", "minLength": 1},
+            "level": {"enum": ["debug", "info", "warn", "error"]},
+            "code": false
+          },
+          "not": {
+            "required": ["code"]
+          },
+          "additionalProperties": true
+        },
+        "trace": {"$ref": "#/$defs/trace"}
+      },
+      "required": ["kind", "log"],
+      "additionalProperties": false
+    }
+  }
+}

agent_first_data-0.16.0/agent_first_data/assets/registry.json

@@ -0,0 +1,260 @@
+{
+  "$schema": "https://agentfirstkit.org/schemas/agent-first-data/registry-v1.schema.json",
+  "schema_version": 1,
+  "name": "agent-first-data",
+  "description": "Machine-readable registry for Agent-First Data suffix semantics.",
+  "safe_integer": {
+    "minimum": -9007199254740991,
+    "maximum": 9007199254740991
+  },
+  "suffixes": [
+    {
+      "suffix": "_ns",
+      "category": "duration",
+      "json_types": ["number"],
+      "unit": "nanosecond",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_us",
+      "category": "duration",
+      "json_types": ["number"],
+      "unit": "microsecond",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_ms",
+      "category": "duration",
+      "json_types": ["number"],
+      "unit": "millisecond",
+      "formatting": {"strip_key": true, "plain_yaml": "duration_ms"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_s",
+      "category": "duration",
+      "json_types": ["number"],
+      "unit": "second",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_minutes",
+      "category": "duration",
+      "json_types": ["number"],
+      "unit": "minute",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit_word"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_hours",
+      "category": "duration",
+      "json_types": ["number"],
+      "unit": "hour",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit_word"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_days",
+      "category": "duration",
+      "json_types": ["number"],
+      "unit": "day",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit_word"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_epoch_s",
+      "category": "timestamp",
+      "json_types": ["integer"],
+      "unit": "unix_epoch_second",
+      "formatting": {"strip_key": true, "plain_yaml": "rfc3339_datetime"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true}
+    },
+    {
+      "suffix": "_epoch_ms",
+      "category": "timestamp",
+      "json_types": ["integer"],
+      "unit": "unix_epoch_millisecond",
+      "formatting": {"strip_key": true, "plain_yaml": "rfc3339_datetime"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true}
+    },
+    {
+      "suffix": "_epoch_ns",
+      "category": "timestamp",
+      "json_types": ["string"],
+      "unit": "unix_epoch_nanosecond",
+      "formatting": {"strip_key": true, "plain_yaml": "rfc3339_datetime"},
+      "redaction": {"mode": "none"},
+      "constraints": {"decimal_integer_string": true}
+    },
+    {
+      "suffix": "_rfc3339",
+      "category": "timestamp",
+      "json_types": ["string"],
+      "unit": "rfc3339_datetime",
+      "formatting": {"strip_key": true, "plain_yaml": "pass_through"},
+      "redaction": {"mode": "none"},
+      "constraints": {"rfc3339_datetime": true}
+    },
+    {
+      "suffix": "_rfc3339_date",
+      "category": "strict_string",
+      "json_types": ["string"],
+      "unit": "rfc3339_full_date",
+      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
+      "redaction": {"mode": "none"},
+      "constraints": {"rfc3339_date": true}
+    },
+    {
+      "suffix": "_rfc3339_time",
+      "category": "strict_string",
+      "json_types": ["string"],
+      "unit": "rfc3339_partial_time",
+      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
+      "redaction": {"mode": "none"},
+      "constraints": {"rfc3339_time": true}
+    },
+    {
+      "suffix": "_bcp47",
+      "category": "strict_string",
+      "json_types": ["string"],
+      "unit": "bcp47_language_tag",
+      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
+      "redaction": {"mode": "none"},
+      "constraints": {"string": true}
+    },
+    {
+      "suffix": "_utc_offset",
+      "category": "strict_string",
+      "json_types": ["string"],
+      "unit": "fixed_utc_offset",
+      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
+      "redaction": {"mode": "none"},
+      "constraints": {"utc_offset": true}
+    },
+    {
+      "suffix": "_bytes",
+      "category": "size",
+      "json_types": ["integer"],
+      "unit": "byte",
+      "formatting": {"strip_key": true, "plain_yaml": "binary_size"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true, "minimum": 0}
+    },
+    {
+      "suffix": "_size",
+      "category": "size",
+      "json_types": ["string"],
+      "unit": "byte_size_input",
+      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
+      "redaction": {"mode": "none"},
+      "constraints": {"parse_size_units": ["B", "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB"]}
+    },
+    {
+      "suffix": "_percent",
+      "category": "ratio",
+      "json_types": ["number"],
+      "unit": "percent",
+      "formatting": {"strip_key": true, "plain_yaml": "append_percent"},
+      "redaction": {"mode": "none"},
+      "constraints": {"number": true}
+    },
+    {
+      "suffix": "_msats",
+      "category": "currency",
+      "json_types": ["integer", "string"],
+      "unit": "millisatoshi",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer_or_decimal_integer_string": true}
+    },
+    {
+      "suffix": "_sats",
+      "category": "currency",
+      "json_types": ["integer", "string"],
+      "unit": "satoshi",
+      "formatting": {"strip_key": true, "plain_yaml": "append_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer_or_decimal_integer_string": true}
+    },
+    {
+      "suffix": "_usd_cents",
+      "category": "currency",
+      "json_types": ["integer"],
+      "unit": "usd_cent",
+      "formatting": {"strip_key": true, "plain_yaml": "currency_minor_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true}
+    },
+    {
+      "suffix": "_eur_cents",
+      "category": "currency",
+      "json_types": ["integer"],
+      "unit": "eur_cent",
+      "formatting": {"strip_key": true, "plain_yaml": "currency_minor_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true}
+    },
+    {
+      "suffix": "_jpy",
+      "category": "currency",
+      "json_types": ["integer"],
+      "unit": "jpy",
+      "formatting": {"strip_key": true, "plain_yaml": "currency_major_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true}
+    },
+    {
+      "suffix": "_{code}_cents",
+      "category": "currency",
+      "json_types": ["integer"],
+      "unit": "currency_minor_unit",
+      "formatting": {"strip_key": true, "plain_yaml": "currency_code_minor_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true, "code_pattern": "^[A-Za-z]{3,4}$"}
+    },
+    {
+      "suffix": "_{code}_micro",
+      "category": "currency",
+      "json_types": ["integer"],
+      "unit": "currency_micro_unit",
+      "formatting": {"strip_key": true, "plain_yaml": "currency_code_micro_unit"},
+      "redaction": {"mode": "none"},
+      "constraints": {"integer": true, "code_pattern": "^[A-Za-z]{3,4}$"}
+    },
+    {
+      "suffix": "_secret",
+      "category": "sensitive",
+      "json_types": ["any"],
+      "unit": null,
+      "formatting": {"strip_key": true, "plain_yaml": "redacted"},
+      "redaction": {"mode": "whole_value", "marker": "***"},
+      "constraints": {"free_text_detection": false}
+    },
+    {
+      "suffix": "_url",
+      "category": "sensitive",
+      "json_types": ["string"],
+      "unit": "url",
+      "formatting": {"strip_key": false, "plain_yaml": "scrub_url"},
+      "redaction": {
+        "mode": "url_components",
+        "userinfo_password": true,
+        "query_param_secret_suffix": "_secret",
+        "marker": "***"
+      },
+      "constraints": {"single_url_string": true, "free_text_detection": false}
+    }
+  ]
+}

agent_first_data-0.16.0/agent_first_data/assets/skills/agent-first-data/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: agent-first-data
+description: Apply Agent-First Data naming, redaction, formatting, protocol envelope, logging, and CLI lint/validate workflows when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, or CLI output in any language. Use proactively before adding, renaming, serializing, or changing public API, wire, database, or persistent field names that may need AFDATA suffixes.
+---
+
+<!-- Canonical source: skills/agent-first-data/SKILL.md.
+     Mirrored byte-for-byte into go/python/typescript assets/ by scripts/sync_offline_assets.py.
+     Edit only here; run that script (checked by scripts/test.sh) to propagate. -->
+
+# Agent-First Data
+
+Use AFDATA when naming fields or reviewing structured output. The contract is naming-based: suffixes communicate units, formatting, and redaction semantics without relying on free-text inference.
+
+## Read references as needed
+
+- `references/rules.md` — detailed suffix rules, output formatting, protocol templates, logging, CLI flags, and review checklist.
+- `references/registry.json` — machine-readable suffix registry; use this as the exact source for suffix metadata.
+- `references/protocol-v1.schema.json` — protocol event schema for `kind:"result"`, `kind:"error"`, `kind:"progress"`, and `kind:"log"` envelopes.
+
+## Naming and redaction decisions
+
+- Add unit suffixes to ambiguous numeric fields: `_ms`, `_s`, `_bytes`, `_percent`, `_sats`, `_msats`, currency suffixes, and timestamp suffixes.
+- Use `_secret` for values/subtrees that must redact to `***` in every output format.
+- Use `_url` only for whole URL values whose userinfo password or suffix-named secret query params should be scrubbed.
+- Do not scan arbitrary free text for secrets. Rename fields or configure explicit secret names at the serialization boundary.
+- Before changing public API, wire, database, or persistent field names, report the compatibility impact and get approval.
+
+## Evaluation rules
+
+- Trigger this skill for field naming, structured output, configs, logs, CLI output, protocol events, MCP/HTTP/SSE payloads, database columns, wire fields, or persisted JSON. Do not wait for the user to say "AFDATA" when the work changes those surfaces.
+- Treat `references/registry.json` and `references/protocol-v1.schema.json` as authoritative. Do not replace them with invented suffix meanings, a reduced schema, or free-text interpretation.
+- For secrets, fix the field name or serializer configuration. Use `_secret` or configured exact secret names; do not rely on scanning arbitrary strings or object debug output.
+- Run `afdata lint` on JSON/JSONL examples, JSON Schema, MCP schemas, or serialized samples when the CLI is available. Run `afdata validate` on finite protocol events/streams. If a check cannot run, report that explicitly.
+- Before modifying an external project's public API, wire format, database schema, or persisted field names, stop and report the compatibility impact; request approval before applying the change.
+
+## Redaction behavior contract
+
+Fields named `_secret` or `_url` and values passing through AFDATA output formatters (`output_json`, `output_yaml`, `output_plain`) are automatically redacted: secrets become `***`, URL userinfo passwords and suffix-named query parameters are scrubbed. When serializing outside output formatters (HTTP, MCP, SSE), call `redacted_value()` or `redact_url_secrets()` at the serialization boundary. PII redaction, domain-specific privacy policies (header allowlists, API scope sensitivity), and per-field secret naming are each spore's responsibility; the library provides field-name-based mechanics only.
+
+## Logging behavior contract
+
+One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serialization via `cli_output()` applies output formatting. Long-running services or processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) initialize with `afdata_tracing::try_init()` (Rust only) to wire process-wide logging; other languages emit log events explicitly via builders or integrate their own structured logging.
+
+## CLI workflow
+
+When the project has the `afdata` CLI available, use it for deterministic checks:
+
+```bash
+afdata lint <file-or-stdin>
+afdata validate <file-or-stdin>
+```
+
+- Run `afdata lint` for ordinary JSON/JSONL, JSON Schema, or MCP input/output schemas.
+- Run `afdata validate` for AFDATA protocol events or finite event streams.
+- Treat findings as contract issues unless the owning tool intentionally documents a non-AFDATA field.
+
+## Review checklist
+
+1. Numeric fields with units carry the right suffix and safe integer/string representation.
+2. Timestamps use `_epoch_s`, `_epoch_ms`, decimal-string `_epoch_ns`, or `_rfc3339`.
+3. Secrets use `_secret` or configured exact secret names; no fallback path leaks them.
+4. CLI output uses AFDATA helpers for JSON/YAML/plain formatting and structured errors.
+5. Logs use AFDATA structured logging or equivalent field-name redaction.
+6. Transport payloads preserve the protocol envelope when AFDATA compliance is claimed.