tidemark 0.1.0__tar.gz

tidemark-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Run linting
+        run: make lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: taiki-e/install-action@nextest
+
+      - name: Run tests
+        run: make test
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@cargo-tarpaulin
+      - name: Generate coverage
+        run: cargo tarpaulin --out xml
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: cobertura.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  all-checks-passed:
+    name: All checks passed
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    if: always()
+    steps:
+      - name: Verify all checks passed
+        run: |
+          if [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" == "true" ]; then
+            echo "Some checks failed or were cancelled"
+            exit 1
+          fi
+          echo "All checks passed"

tidemark-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,393 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*.[0-9]*.[0-9]*'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Dry run mode (skip actual publishing)'
+        required: false
+        default: true
+        type: boolean
+      skip_crates_io:
+        description: 'Skip publishing to crates.io (if already published)'
+        required: false
+        default: false
+        type: boolean
+      skip_pypi:
+        description: 'Skip publishing to PyPI (if already published)'
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: write
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: taiki-e/install-action@nextest
+
+      - name: Verify Cargo.lock is up to date
+        run: cargo check --locked
+
+      - name: Run tests
+        run: make test
+
+  build:
+    name: Build ${{ matrix.target }}
+    needs: test
+    timeout-minutes: 30
+    # Guard: self-hosted runners only execute on trusted events (tag push,
+    # workflow_dispatch). Fork PRs must never dispatch jobs to self-hosted.
+    if: github.event_name != 'pull_request'
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: [self-hosted, Linux, ARM64]
+            target: aarch64-unknown-linux-gnu
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+          - os: [self-hosted, macOS, ARM64]
+            target: x86_64-apple-darwin
+          - os: [self-hosted, macOS, ARM64]
+            target: aarch64-apple-darwin
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Preserve target/ between runs on self-hosted runners for cargo
+          # incremental rebuild. GitHub-hosted runners start clean each job
+          # regardless of this setting, so this only affects self-hosted.
+          clean: false
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Prepare cargo cache dirs (arm64 linux)
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        run: mkdir -p "${RUNNER_TOOL_CACHE}/cargo-cache/registry" "${RUNNER_TOOL_CACHE}/cargo-cache/git"
+
+      - name: Clean stale dist
+        # Keep dist/ fresh each run so previous builds cannot leak artifacts
+        # into the upload. Self-hosted runners do not clean automatically.
+        # On the arm64 linux runner, maturin-action runs as root inside the
+        # manylinux container and leaves root-owned files in dist/; clean
+        # via docker so the unprivileged runner user can proceed.
+        shell: bash
+        run: |
+          if [[ "${{ matrix.target }}" == "aarch64-unknown-linux-gnu" ]]; then
+            docker run --rm -v "${GITHUB_WORKSPACE}:/io" alpine rm -rf /io/dist /io/target/wheels
+          else
+            rm -rf dist target/wheels
+          fi
+
+      - name: Install cross-compilation tools
+        # Only needed on GitHub-hosted linux where the arm64 toolchain must
+        # be cross-installed. The self-hosted arm64 runner is native.
+        if: matrix.target == 'aarch64-unknown-linux-gnu' && runner.arch != 'ARM64'
+        run: sudo apt-get update && sudo apt-get install -y gcc-aarch64-linux-gnu
+
+      - name: Install uv
+        if: matrix.target != 'aarch64-unknown-linux-gnu'
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install maturin and zig
+        # maturin-action provides its own maturin inside the manylinux
+        # container for the arm64 linux build, so skip the host install
+        # on the self-hosted runner.
+        if: matrix.target != 'aarch64-unknown-linux-gnu'
+        shell: bash
+        run: |
+          uv venv "${RUNNER_TEMP}/build-venv"
+          VENV_BIN="${RUNNER_TEMP}/build-venv/bin"
+          [ -d "$VENV_BIN" ] || VENV_BIN="${RUNNER_TEMP}/build-venv/Scripts"
+          uv pip install --python "$VENV_BIN/python" maturin ziglang
+          echo "$VENV_BIN" >> "$GITHUB_PATH"
+
+      - name: Build wheel (arm64 linux via maturin-action)
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        uses: PyO3/maturin-action@v1
+        with:
+          target: aarch64-unknown-linux-gnu
+          args: --release --out dist
+          manylinux: manylinux_2_28
+          # Mount persistent cargo cache into the manylinux container so
+          # dependency downloads survive between jobs on the self-hosted
+          # runner.
+          docker-options: -v ${{ runner.tool_cache }}/cargo-cache/registry:/root/.cargo/registry -v ${{ runner.tool_cache }}/cargo-cache/git:/root/.cargo/git
+
+      - name: Build wheel
+        if: matrix.target != 'aarch64-unknown-linux-gnu'
+        shell: bash
+        run: |
+          case "${{ matrix.target }}" in
+            *-gnu)
+              maturin build --release --target ${{ matrix.target }} --compatibility manylinux_2_28 --zig --out dist
+              ;;
+            *)
+              maturin build --release --target ${{ matrix.target }} --out dist
+              ;;
+          esac
+
+      - name: Build binary (arm64 linux via cargo-zigbuild)
+        # On the Pi runner build natively with cargo-zigbuild targeting
+        # glibc 2.28 for wide distro compatibility. Use a separate target
+        # directory so host cargo does not conflict with root-owned files
+        # left behind by the maturin-action container build in target/.
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        env:
+          CARGO_TARGET_DIR: target-host
+        run: cargo zigbuild --release --target aarch64-unknown-linux-gnu.2.28
+
+      - name: Build binary
+        if: matrix.target != 'aarch64-unknown-linux-gnu'
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+        run: cargo build --release --target ${{ matrix.target }}
+
+      - name: Verify binary
+        if: ${{ !contains(matrix.target, 'aarch64-unknown-linux') }}
+        shell: bash
+        run: |
+          if [[ "${{ runner.os }}" == "Windows" ]]; then
+            ./target/${{ matrix.target }}/release/tidemark.exe --version
+          else
+            ./target/${{ matrix.target }}/release/tidemark --version
+          fi
+
+      - name: Create release archive
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          ARCHIVE_NAME="tidemark-${VERSION}-${{ matrix.target }}"
+
+          mkdir -p release-package
+
+          if [[ "${{ runner.os }}" == "Windows" ]]; then
+            cp "target/${{ matrix.target }}/release/tidemark.exe" release-package/tidemark.exe
+            cd release-package
+            powershell -command "Compress-Archive -Path tidemark.exe -DestinationPath ../${ARCHIVE_NAME}.zip"
+            cd ..
+            powershell -command "Get-FileHash -Path '${ARCHIVE_NAME}.zip' -Algorithm SHA256 | Select-Object -ExpandProperty Hash" > "${ARCHIVE_NAME}.zip.sha256"
+          else
+            if [[ "${{ matrix.target }}" == "aarch64-unknown-linux-gnu" ]]; then
+              BIN_PATH="target-host/aarch64-unknown-linux-gnu/release/tidemark"
+            else
+              BIN_PATH="target/${{ matrix.target }}/release/tidemark"
+            fi
+            cp "$BIN_PATH" release-package/tidemark
+            tar -czf "${ARCHIVE_NAME}.tar.gz" -C release-package tidemark
+
+            if [[ "${{ runner.os }}" == "macOS" ]]; then
+              shasum -a 256 "${ARCHIVE_NAME}.tar.gz" > "${ARCHIVE_NAME}.tar.gz.sha256"
+            else
+              sha256sum "${ARCHIVE_NAME}.tar.gz" > "${ARCHIVE_NAME}.tar.gz.sha256"
+            fi
+          fi
+
+          rm -rf release-package
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          path: dist/*.whl
+          name: wheel-${{ matrix.target }}
+
+      - name: Upload release archives
+        uses: actions/upload-artifact@v4
+        with:
+          path: |
+            tidemark-*-${{ matrix.target }}.tar.gz*
+            tidemark-*-${{ matrix.target }}.zip*
+          name: release-${{ matrix.target }}
+
+  sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Install maturin
+        shell: bash
+        run: |
+          uv venv "${RUNNER_TEMP}/build-venv"
+          uv pip install --python "${RUNNER_TEMP}/build-venv/bin/python" maturin
+          echo "${RUNNER_TEMP}/build-venv/bin" >> "$GITHUB_PATH"
+
+      - name: Build sdist
+        run: maturin sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          path: target/wheels/*.tar.gz
+          name: sdist
+
+  release:
+    runs-on: ubuntu-latest
+    needs: [build, sdist]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: false
+
+      - name: Publish to crates.io
+        if: ${{ inputs.dry_run != true && inputs.skip_crates_io != true }}
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish --locked
+
+      - name: Test crates.io publish (dry run)
+        if: ${{ inputs.dry_run == true && inputs.skip_crates_io != true }}
+        run: |
+          echo "DRY RUN: Would publish to crates.io"
+          cargo publish --dry-run --locked
+
+      - name: Skip crates.io publishing
+        if: ${{ inputs.skip_crates_io == true }}
+        run: echo "Skipping crates.io publishing as requested"
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Publish to PyPI
+        if: ${{ inputs.dry_run != true && inputs.skip_pypi != true }}
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          uv tool run twine upload artifacts/wheel-*/*.whl artifacts/sdist/*.tar.gz
+
+      - name: Test PyPI upload (dry run)
+        if: ${{ inputs.dry_run == true && inputs.skip_pypi != true }}
+        run: |
+          echo "DRY RUN: Would upload to PyPI:"
+          find artifacts/wheel-* -name "*.whl" -type f | sort
+          find artifacts/sdist -name "*.tar.gz" -type f | sort
+          uv tool run twine check artifacts/wheel-*/*.whl artifacts/sdist/*.tar.gz
+
+      - name: Skip PyPI publishing
+        if: ${{ inputs.skip_pypi == true }}
+        run: echo "Skipping PyPI publishing as requested"
+
+      - name: Create Release
+        if: ${{ inputs.dry_run != true }}
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            artifacts/release-*/tidemark-*.tar.gz
+            artifacts/release-*/tidemark-*.tar.gz.sha256
+            artifacts/release-*/tidemark-*.zip
+            artifacts/release-*/tidemark-*.zip.sha256
+
+      - name: Dry Run Summary
+        if: ${{ inputs.dry_run == true }}
+        run: |
+          echo "Dry run complete. Artifacts built but nothing published."
+          echo "Archives:"
+          find artifacts/release-* -type f | sort
+
+  update-homebrew:
+    needs: release
+    if: ${{ !inputs.dry_run }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: /tmp/artifacts
+
+      - name: Compute SHA256 hashes
+        id: hashes
+        run: |
+          for target in x86_64-apple-darwin aarch64-apple-darwin x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu; do
+            sha=$(cat /tmp/artifacts/release-${target}/tidemark-${{ github.ref_name }}-${target}.tar.gz.sha256 | awk '{print $1}')
+            key=$(echo "${target}" | tr '-' '_')
+            echo "${key}=${sha}" >> "$GITHUB_OUTPUT"
+          done
+
+      - name: Update Homebrew formula
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          VERSION="${{ github.ref_name }}"
+          VERSION_NUM="${VERSION#v}"
+
+          cat > /tmp/tidemark.rb << 'FORMULA'
+          class Tidemark < Formula
+            desc "Snapshot a directory tree and diff what changed - no git required"
+            homepage "https://github.com/rvben/tidemark"
+            version "VERSION_NUM"
+            license "MIT"
+
+            on_macos do
+              if Hardware::CPU.arm?
+                url "https://github.com/rvben/tidemark/releases/download/VERSION/tidemark-VERSION-aarch64-apple-darwin.tar.gz"
+                sha256 "SHA_AARCH64_APPLE_DARWIN"
+              else
+                url "https://github.com/rvben/tidemark/releases/download/VERSION/tidemark-VERSION-x86_64-apple-darwin.tar.gz"
+                sha256 "SHA_X86_64_APPLE_DARWIN"
+              end
+            end
+
+            on_linux do
+              if Hardware::CPU.arm?
+                url "https://github.com/rvben/tidemark/releases/download/VERSION/tidemark-VERSION-aarch64-unknown-linux-gnu.tar.gz"
+                sha256 "SHA_AARCH64_UNKNOWN_LINUX_GNU"
+              else
+                url "https://github.com/rvben/tidemark/releases/download/VERSION/tidemark-VERSION-x86_64-unknown-linux-gnu.tar.gz"
+                sha256 "SHA_X86_64_UNKNOWN_LINUX_GNU"
+              end
+            end
+
+            def install
+              bin.install "tidemark"
+            end
+
+            test do
+              system "#{bin}/tidemark", "--version"
+            end
+          end
+          FORMULA
+
+          sed -i "s/VERSION_NUM/${VERSION_NUM}/g" /tmp/tidemark.rb
+          sed -i "s/VERSION/${VERSION}/g" /tmp/tidemark.rb
+          sed -i "s/SHA_AARCH64_APPLE_DARWIN/${{ steps.hashes.outputs.aarch64_apple_darwin }}/g" /tmp/tidemark.rb
+          sed -i "s/SHA_X86_64_APPLE_DARWIN/${{ steps.hashes.outputs.x86_64_apple_darwin }}/g" /tmp/tidemark.rb
+          sed -i "s/SHA_AARCH64_UNKNOWN_LINUX_GNU/${{ steps.hashes.outputs.aarch64_unknown_linux_gnu }}/g" /tmp/tidemark.rb
+          sed -i "s/SHA_X86_64_UNKNOWN_LINUX_GNU/${{ steps.hashes.outputs.x86_64_unknown_linux_gnu }}/g" /tmp/tidemark.rb
+
+          # Clone tap repo, update formula, push
+          git clone https://x-access-token:${GH_TOKEN}@github.com/rvben/homebrew-tap.git /tmp/tap
+          mkdir -p /tmp/tap/Formula
+          cp /tmp/tidemark.rb /tmp/tap/Formula/tidemark.rb
+          cd /tmp/tap
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Formula/tidemark.rb
+          git diff --cached --quiet || git commit -m "Update tidemark to ${VERSION}"
+          git push

tidemark-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+/target
+/CLAUDE.local.md
+/dist
+/target-host
+*.whl
+/docs/superpowers/

tidemark-0.1.0/AGENTS.md

@@ -0,0 +1,94 @@
+# tidemark for agents
+
+`tidemark` is a deterministic filesystem snapshot/diff tool designed to be driven
+by AI agents. This document is the operational contract.
+
+## Discover capabilities
+
+Run `tidemark schema` first. It returns a clispec v0.1 document listing every
+command, its arguments (name, type, required, default), output fields, error
+kinds (each with a `retryable` flag), exit-code semantics, and which commands
+mutate state (`mutating: true`). The schema is the source of truth; prefer it
+over parsing help text.
+
+## Output contract
+
+- Output is **JSON by default when stdout is not a TTY**. You never need a flag,
+  but you may pass `--json` (or `--output json`) to be explicit.
+- **stdout carries data only.** All diagnostics and the human summary line go to
+  stderr. Piping stdout to a JSON parser is always safe.
+- `diff` returns a flat object:
+
+  ```json
+  {
+    "changes": [ { "kind": "modified", "path": "src/a.rs",
+                   "old_hash": "blake3:...", "new_hash": "blake3:...",
+                   "size_delta": 12 } ],
+    "added": 0, "modified": 1, "deleted": 0, "renamed": 0,
+    "total": 1, "limit": null, "offset": 0
+  }
+  ```
+
+- `list` uses the envelope `{"items": [...], "total": N, "limit": L, "offset": O}`.
+- Bound large results with `--limit` / `--offset`, and trim fields with
+  `--fields path,kind`. These flags are global (accepted on any command).
+- Running `tidemark` with no command lists stored snapshots.
+
+## Recommended pattern
+
+```
+tidemark snap -o pre.tidemark        # portable manifest (or: tidemark snap before)
+<run the operation under test>
+tidemark diff pre.tidemark @ --json  # @ means "the current tree"
+```
+
+A ref (the `A`/`B` of `diff`) is one of: a store label, a path to a manifest
+file, or `@` for the live tree. `tidemark diff before` is shorthand for
+`tidemark diff before @`. A bare ref resolves to a store label first, falling
+back to a same-named file only if no such label exists. `tidemark init` creates
+the `.tidemark/` store explicitly (idempotent).
+
+## Determinism and idempotency
+
+- `tree_digest` is a BLAKE3 Merkle root over the sorted entries. Two snapshots of
+  an unchanged tree are byte-for-byte identical in digest.
+- `mtime` never affects change detection, so rebuilds and `touch` do not produce
+  spurious diffs.
+- `tidemark snap LABEL` on an unchanged tree is a success no-op (exit 0).
+  Re-using a label for a *different* tree returns the `conflict` error kind
+  (exit 2) unless you pass `--force`.
+- A file that vanishes between the directory walk and its read is skipped, so a
+  concurrent deletion mid-snapshot does not abort the whole snapshot.
+
+## Exit codes
+
+- Default: `0` success, `2` error.
+- `diff --exit-code`: `0` no changes, `1` changes found, `2` error. Use this when
+  you only need a yes/no "did anything change" signal.
+
+## Errors
+
+Always to stderr, shape:
+
+```json
+{"error": {"kind": "not_found", "message": "...", "retryable": false}}
+```
+
+Kinds: `not_found`, `conflict`, `invalid_input`, `unsupported`, and `io`
+(the only `retryable: true` kind - safe to retry transient filesystem errors).
+Argument-parse failures are also reported as `invalid_input` JSON on stderr.
+
+## Content diffs
+
+`diff --content` emits a real unified line diff in each modified change's
+`content_preview` field, reconstructed from text content stored in both
+manifests. Because every snapshot stores inline text content (UTF-8 files under
+256 KiB), this works even between two stored manifests, not just against the live
+tree. Binary, oversized, or `--no-content` files report that the content was
+unavailable instead.
+
+## Safety
+
+- Destructive `rm` refuses to run without `--yes` when stdin is not a TTY.
+- tidemark never records its own `.tidemark/` store directory in a snapshot.
+- Labels are validated against path traversal and control characters.

tidemark-0.1.0/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.

tidemark-0.1.0/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+make check          # lint + test (CI runs this)
+make build          # cargo build --release
+make test           # cargo nextest run + cargo test --doc
+make lint           # cargo fmt --check + cargo clippy -D warnings
+make fmt            # auto-format
+make score          # build release + clispec score ./target/release/tidemark
+make ci             # check + score
+make install        # cargo install --path .
+cargo nextest run <name>   # run a single test by name
+```
+
+## Architecture
+
+tidemark is a Rust CLI that snapshots a directory tree into a deterministic
+BLAKE3 manifest and diffs two snapshots (added/modified/deleted/renamed) with no
+git required. Binary name: `tidemark`. Also published to PyPI (`uvx tidemark`)
+and Homebrew (`brew install rvben/tap/tidemark`). Scores 100/100 against
+[The CLI Spec](https://clispec.dev).
+
+### Pure-core + thin-shell layout
+
+- **Pure (no I/O, unit-tested directly):** `manifest` (`Manifest`/`Entry`, Merkle
+  `tree_digest`), `diff` (classification, rename detection, `unified_diff`).
+- **I/O wrappers:** `walk` (directory traversal via the `ignore` crate,
+  `require_git(false)`), `hash` (`hash_bytes`), `builder` (`build_manifest` +
+  `SnapOptions`), `store` (`.tidemark/` labeled snapshot store), `refs` (resolve a
+  ref: store label | manifest file | `@` current tree).
+- **Shell:** `output` (JSON/table, pagination, field selection), `schema` (the
+  clispec v0.1 document), `cli` (clap tree, dispatch, exit codes), `error`
+  (`TidemarkError` + clispec error kinds).
+
+### Key patterns
+
+- **clispec scorer probes the first non-mutating command** for structured-output
+  and stream checks, so `list` MUST stay ordered before `diff` in `schema.rs`
+  (`tidemark diff` errors with no snapshot; `list` always exits 0 with an
+  envelope). Reordering drops the score.
+- **Schema matches `clispec.dev/schema/v0.1.json`:** top-level
+  `name`/`version`/`commands`/`errors`; per-command `mutating` boolean +
+  `output_fields`; `errors` is a top-level array of `{kind, retryable}`.
+- **`mtime` is informational only** - excluded from `tree_digest` and change
+  detection, so `touch`/rebuilds never create false positives.
+- **Rename detection only on unambiguous `(hash, mode, kind)` signatures**
+  (exactly one deleted + one added share it); duplicate-content files stay as
+  add/delete.
+- **Inline content** stored for UTF-8 files <= 256 KiB (`CONTENT_CAP_BYTES`)
+  enables real two-sided `diff --content`, even between two stored manifests.
+- **stdout/stderr flushed before `process::exit`** in `main.rs` (exit skips
+  destructors, so a buffered pipe could otherwise truncate).
+- Destructive `rm` requires `--yes` when stdin is not a TTY. tidemark never
+  records its own `.tidemark/` store in a snapshot. Labels are validated against
+  path traversal and control characters.
+
+### CI / release
+
+All CI steps are make targets; the pipeline only runs make. `ci.yml` runs
+lint/test/coverage on push and PR. `release.yml` triggers on a `v*` tag (or
+manual dispatch, dry-run by default) and publishes to crates.io + PyPI + a
+GitHub release, then updates the Homebrew tap formula. Release is driven by
+`make release-patch|minor|major` (vership).
+
+## Documentation
+
+- `README.md` - human-facing usage.
+- `AGENTS.md` - the agent-facing operational contract.
+- `docs/superpowers/` - design spec and implementation plan (gitignored).