mojiblame 0.1.0__tar.gz

mojiblame-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Trusted publishing: PyPI verifies this workflow's identity directly, so
+      # there is no long-lived API token sitting in repository secrets.
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - run: uv sync --all-extras --dev
+      - run: uv run python -m pytest -q
+      - run: uv build
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

mojiblame-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: test
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  test:
+    # Windows is not an afterthought here - it is where most of this damage is
+    # created, so a green Windows job is the point rather than a bonus.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Configure git for the synthetic-repo tests
+        run: |
+          git config --global user.email "ci@example.invalid"
+          git config --global user.name "ci"
+          git config --global init.defaultBranch main
+
+      - run: uv sync --all-extras --dev
+
+      - run: uv run python -m pytest -q
+
+      - name: Dogfood - the tool must find nothing in its own source
+        run: uv run mojiblame scan .

mojiblame-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# mojiblame's own undo journals
+.mojiblame/
+
+# Ic devir notu - repoda yeri yok
+docs/BRIEF-visuals.md

mojiblame-0.1.0/.mojiblameignore

@@ -0,0 +1,4 @@
+# Test fixtures and the visuals brief carry broken characters on purpose:
+# they are the samples this tool is built to recognise.
+tests/
+docs/BRIEF-visuals.md

mojiblame-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: mojiblame
+  name: mojiblame (encoding forensics)
+  description: >-
+    Refuses commits containing mojibake, non-UTF-8 files, or characters that were
+    destroyed by a bad decode.
+  entry: mojiblame-precommit
+  language: python
+  types: [text]

mojiblame-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mojiblame-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.5
+Name: mojiblame
+Version: 0.1.0
+Summary: Git-aware encoding forensics: find which commit corrupted your text, prove every fix byte-exact, recover what other tools call unrecoverable.
+Project-URL: Homepage, https://github.com/Golemozan/mojiblame
+Project-URL: Repository, https://github.com/Golemozan/mojiblame
+Project-URL: Issues, https://github.com/Golemozan/mojiblame/issues
+Author: Ozan
+License: MIT
+License-File: LICENSE
+Keywords: cp1252,encoding,forensics,git,mojibake,pre-commit,utf-8,windows
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.10
+Requires-Dist: charset-normalizer>=3.3
+Requires-Dist: ftfy>=6.2
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# mojiblame
+
+<!-- mojiblame:ignore-file — this README intentionally contains damaged encoding examples. -->
+
+**Git-aware encoding forensics.** Find the commit that corrupted your text, prove every fix
+byte-exact, and recover characters other tools call unrecoverable.
+
+[![test](https://github.com/Golemozan/mojiblame/actions/workflows/test.yml/badge.svg)](https://github.com/Golemozan/mojiblame/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/mojiblame)](https://pypi.org/project/mojiblame/)
+[![Python](https://img.shields.io/pypi/pyversions/mojiblame)](https://pypi.org/project/mojiblame/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+![mojiblame — git-aware encoding forensics](docs/assets/hero.png)
+
+```console
+$ mojiblame scan .
+
+damage    proof       file             detail
+lossy     unprovable  docs/kurulum.md  19 character(s) destroyed (U+FFFD) - try: mojiblame blame
+mojibake  byte-exact  src/tr.json      latin-1 -> utf-8, 1 layer(s), reversal verified byte-exact
+
+  2 scanned  ·  2 damaged  ·  1 fixable now  ·  1 needs history (mojiblame blame <file>)
+```
+
+---
+
+## The problem
+
+AI coding agents read and write your files through shells and subprocesses. On Windows —
+and anywhere the default codepage is not UTF-8 — that pipeline silently mangles non-ASCII
+text. Nobody notices, because nothing fails: the agent writes `ö` instead of `ö`, the patch
+context stops matching, a hook prints garbage, and the damage sits in the repo for weeks.
+
+This is not hypothetical. It has been reported against
+[Codex on Windows](https://github.com/openai/codex/issues/4131) — Turkish characters coming
+back wrong from `Get-Content`/`Set-Content` — and again as
+[mojibake breaking patch application](https://community.openai.com/t/codex-on-windows-utf-8-mojibake-and-patch-context-mismatch-issues/1384116),
+where the agent can no longer edit a file because the bytes it read are not the bytes on disk.
+
+Existing tools look at a file **as it is now** and **guess**. `ftfy` is an excellent library
+for repairing a string, but it does not scan a repository, does not know your git history,
+and cannot tell you whether its repair is correct or merely plausible.
+
+![How silent codepage corruption enters a repository](docs/assets/pipeline.svg)
+
+## What mojiblame does differently
+
+### 1. It separates three kinds of damage that other tools blur together
+
+| | What happened | Fix | Standard of proof |
+|---|---|---|---|
+| **wrong-codec** | The bytes are not UTF-8 at all (cp1254, cp1251, latin-1…). The text is intact; only the codec is wrong. | transcode | **reversible** — re-encoding restores the original bytes. The codec itself is inferred, and we say so. |
+| **mojibake** | The file *is* valid UTF-8, but the characters are wrong: UTF-8 was decoded as a legacy codepage and re-encoded. `ö` → `ö`. Stacks to several layers. | repair | **byte-exact** — see below |
+| **lossy** | `U+FFFD` replacement characters. The bytes were destroyed at decode time. They are not in the file any more. | *none* | **unprovable from the file** — only history can help |
+
+The distinction is not academic. A tool that treats the third case like the first will happily
+"fix" a file and hand you plausible fiction.
+
+### 2. Every fix is proven, or it is not applied
+
+For mojibake we take the repair plan, **invert it**, and re-apply the inversion to the repaired
+text. If that reproduces the bytes currently on disk exactly, the repair is not a guess: the
+recovered text is a verified preimage of the file as it stands, not the most plausible-looking
+candidate.
+
+If the inversion does not reproduce them, mojiblame reports the finding and **refuses to write**:
+
+```console
+mojibake  unprovable  README.md   looks like partially decoded UTF-8 mojibake,
+                                  but the reversal is not exact - not fixing
+```
+
+No proof, no write. That rule has no exceptions.
+
+### 3. It recovers what the file alone cannot
+
+`U+FFFD` means the bytes are gone, and no amount of cleverness gets them back out of the file.
+But git kept every earlier version. `mojiblame blame` walks that history, finds the commit where
+the damage appeared, works out which decode step caused it, and restores the destroyed
+characters from the last clean version:
+
+```console
+$ mojiblame blame docs/kurulum.md
+
+kurulum.md
+
+  19 character(s) destroyed (U+FFFD)
+  corruption entered   03bbd41  2026-09-02  chore: toplu yeniden bicimlendirme
+  last clean version   c6455a1  2026-09-02  docs: kurulum notlari eklendi
+  transform            cp1254 -> utf-8
+  recoverable          19 / 19  (proof: re-applying the transform reproduces this file exactly)
+```
+
+That last line is the point. We reconstruct the corruption, apply it to the recovered text, and
+check it reproduces today's file byte for byte. If it does, the recovery is a deduction, not a
+best guess — and mojiblame says which one it is either way.
+
+**It splices, it does not revert.** `git checkout <old-sha> -- file` would throw away every
+legitimate edit made since the damage. mojiblame keeps today's file and replaces only the runs
+of destroyed characters.
+
+![mojiblame scan, blame, and fix terminal demo](docs/assets/blame-demo.gif)
+
+## Install
+
+```console
+uv tool install mojiblame     # or: pipx install mojiblame
+```
+
+## Use
+
+```console
+mojiblame scan [PATH]     read-only report, with the standard of proof for each finding
+mojiblame blame <FILE>    which commit broke it, which step, what history can restore
+mojiblame fix [PATH]      apply only the provable fixes; --dry-run, --yes
+mojiblame undo            restore the originals from the last fix
+mojiblame guard [PATH]    exit non-zero if anything is corrupted (CI, hooks)
+mojiblame init            wire it into pre-commit, GitHub Actions, or your agent
+```
+
+`fix` journals the original bytes before it changes anything, so `undo` is byte-identical —
+not "close enough". Inside a git repo, scanning honours `.gitignore`.
+
+## Wire it in
+
+**pre-commit** — the version most people should use, because it runs without anyone remembering it:
+
+```yaml
+repos:
+  - repo: https://github.com/Golemozan/mojiblame
+    rev: v0.1.0
+    hooks:
+      - id: mojiblame
+```
+
+**GitHub Actions** — `mojiblame init --github`, or:
+
+```yaml
+- run: pip install mojiblame
+- run: mojiblame guard .
+```
+
+**Coding agents** — `mojiblame init --claude` installs a `PreToolUse` hook that inspects writes
+*before they reach the disk* and blocks the ones that would introduce corruption. Cleaning up
+afterwards is the losing half of this problem; the agent is told what it was about to corrupt
+and can retry correctly:
+
+```
+mojiblame blocked this write to notes.md: mojibake (cp1254 -> utf-8, 1 layer(s)).
+The text was decoded with the wrong codec somewhere upstream.
+Intended text starts: 'yönetici İŞ şğüöç'
+```
+
+## Suppression
+
+Some files contain broken characters on purpose — documentation about encoding bugs, test
+fixtures, golden files. Two ways to say so:
+
+```gitignore
+# .mojiblameignore
+fixtures/
+*.snapshot
+```
+
+or put `mojiblame:ignore-file` anywhere in the file. The marker is matched against raw bytes,
+so it still works in files that do not decode cleanly — which is exactly where you need it.
+
+## Limitations
+
+Stated plainly, because a forensics tool that oversells itself is worse than none:
+
+- **Codec identification is statistical.** `latin-1` decodes every possible byte sequence, so a
+  clean round-trip proves the transcode is reversible, not that the codec was right. mojiblame
+  reports those as two separate facts and never merges them into one confident claim.
+- **The codec *name* on a mojibake finding may be one of several.** Where two codepages map the
+  characters in a file identically, they are indistinguishable from the bytes — corruption caused
+  by cp1254 is reported as `latin-1 -> utf-8` when the text contains nothing that separates them.
+  The recovered text is the same either way, and it is the part that gets verified; only the label
+  is ambiguous.
+- **Destroyed characters with no clean ancestor stay destroyed.** If a line was first written
+  already broken, no earlier version exists and mojiblame will tell you it recovered `0 / n`
+  rather than inventing text.
+- **History walking assumes damage, once introduced, persists.** That assumption is verified,
+  and the search falls back to a linear scan when a file was broken, fixed, and broken again.
+- Files over 5 MB are skipped by default.
+
+## How it works
+
+```
+detect/facts.py       BOM, line endings, strict UTF-8 decode - facts, no inference
+detect/codecs.py      D1: which legacy codec, and is the transcode reversible
+detect/mojibake.py    D2: repair plan, layer depth, and the inverse-plan proof
+gitfx/repo.py         git, always via bytes - never text=True, never the console codepage
+gitfx/forensics.py    binary-searches history for the commit that introduced the damage
+gitfx/recover.py      splices destroyed runs from the clean version, keeping later edits
+fixing/journal.py     gzipped originals so undo is byte-identical
+hooks/                pre-commit entry point and the agent PreToolUse guard
+```
+
+One detail worth calling out: `gitfx/repo.py` never uses `subprocess(text=True)`. That decodes
+with the console codepage — cp1254 on a Turkish Windows box — which is precisely the bug class
+this tool hunts. A forensics tool that mangles its own evidence is worthless, so every git call
+returns bytes and decoding is always an explicit, local decision.
+
+## Why this exists
+
+A memory system I run injected context into every session for months. It was writing `y���n�`
+where it meant `yönetici`, and nothing ever failed — the sessions just quietly got a little
+worse. The cause was a PowerShell 5.1 hook writing stdout in the console codepage.
+
+Finding it took an afternoon. Knowing *when* it started took git archaeology by hand, and by
+then the answer to "can any of this be recovered?" was pure guesswork. mojiblame is that
+afternoon, made repeatable.
+
+Its first real run, against that same 437-file vault, found four damaged files and named the
+commit responsible for each.
+
+## License
+
+MIT

mojiblame-0.1.0/README.md

@@ -0,0 +1,220 @@
+# mojiblame
+
+<!-- mojiblame:ignore-file — this README intentionally contains damaged encoding examples. -->
+
+**Git-aware encoding forensics.** Find the commit that corrupted your text, prove every fix
+byte-exact, and recover characters other tools call unrecoverable.
+
+[![test](https://github.com/Golemozan/mojiblame/actions/workflows/test.yml/badge.svg)](https://github.com/Golemozan/mojiblame/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/mojiblame)](https://pypi.org/project/mojiblame/)
+[![Python](https://img.shields.io/pypi/pyversions/mojiblame)](https://pypi.org/project/mojiblame/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+![mojiblame — git-aware encoding forensics](docs/assets/hero.png)
+
+```console
+$ mojiblame scan .
+
+damage    proof       file             detail
+lossy     unprovable  docs/kurulum.md  19 character(s) destroyed (U+FFFD) - try: mojiblame blame
+mojibake  byte-exact  src/tr.json      latin-1 -> utf-8, 1 layer(s), reversal verified byte-exact
+
+  2 scanned  ·  2 damaged  ·  1 fixable now  ·  1 needs history (mojiblame blame <file>)
+```
+
+---
+
+## The problem
+
+AI coding agents read and write your files through shells and subprocesses. On Windows —
+and anywhere the default codepage is not UTF-8 — that pipeline silently mangles non-ASCII
+text. Nobody notices, because nothing fails: the agent writes `ö` instead of `ö`, the patch
+context stops matching, a hook prints garbage, and the damage sits in the repo for weeks.
+
+This is not hypothetical. It has been reported against
+[Codex on Windows](https://github.com/openai/codex/issues/4131) — Turkish characters coming
+back wrong from `Get-Content`/`Set-Content` — and again as
+[mojibake breaking patch application](https://community.openai.com/t/codex-on-windows-utf-8-mojibake-and-patch-context-mismatch-issues/1384116),
+where the agent can no longer edit a file because the bytes it read are not the bytes on disk.
+
+Existing tools look at a file **as it is now** and **guess**. `ftfy` is an excellent library
+for repairing a string, but it does not scan a repository, does not know your git history,
+and cannot tell you whether its repair is correct or merely plausible.
+
+![How silent codepage corruption enters a repository](docs/assets/pipeline.svg)
+
+## What mojiblame does differently
+
+### 1. It separates three kinds of damage that other tools blur together
+
+| | What happened | Fix | Standard of proof |
+|---|---|---|---|
+| **wrong-codec** | The bytes are not UTF-8 at all (cp1254, cp1251, latin-1…). The text is intact; only the codec is wrong. | transcode | **reversible** — re-encoding restores the original bytes. The codec itself is inferred, and we say so. |
+| **mojibake** | The file *is* valid UTF-8, but the characters are wrong: UTF-8 was decoded as a legacy codepage and re-encoded. `ö` → `ö`. Stacks to several layers. | repair | **byte-exact** — see below |
+| **lossy** | `U+FFFD` replacement characters. The bytes were destroyed at decode time. They are not in the file any more. | *none* | **unprovable from the file** — only history can help |
+
+The distinction is not academic. A tool that treats the third case like the first will happily
+"fix" a file and hand you plausible fiction.
+
+### 2. Every fix is proven, or it is not applied
+
+For mojibake we take the repair plan, **invert it**, and re-apply the inversion to the repaired
+text. If that reproduces the bytes currently on disk exactly, the repair is not a guess: the
+recovered text is a verified preimage of the file as it stands, not the most plausible-looking
+candidate.
+
+If the inversion does not reproduce them, mojiblame reports the finding and **refuses to write**:
+
+```console
+mojibake  unprovable  README.md   looks like partially decoded UTF-8 mojibake,
+                                  but the reversal is not exact - not fixing
+```
+
+No proof, no write. That rule has no exceptions.
+
+### 3. It recovers what the file alone cannot
+
+`U+FFFD` means the bytes are gone, and no amount of cleverness gets them back out of the file.
+But git kept every earlier version. `mojiblame blame` walks that history, finds the commit where
+the damage appeared, works out which decode step caused it, and restores the destroyed
+characters from the last clean version:
+
+```console
+$ mojiblame blame docs/kurulum.md
+
+kurulum.md
+
+  19 character(s) destroyed (U+FFFD)
+  corruption entered   03bbd41  2026-09-02  chore: toplu yeniden bicimlendirme
+  last clean version   c6455a1  2026-09-02  docs: kurulum notlari eklendi
+  transform            cp1254 -> utf-8
+  recoverable          19 / 19  (proof: re-applying the transform reproduces this file exactly)
+```
+
+That last line is the point. We reconstruct the corruption, apply it to the recovered text, and
+check it reproduces today's file byte for byte. If it does, the recovery is a deduction, not a
+best guess — and mojiblame says which one it is either way.
+
+**It splices, it does not revert.** `git checkout <old-sha> -- file` would throw away every
+legitimate edit made since the damage. mojiblame keeps today's file and replaces only the runs
+of destroyed characters.
+
+![mojiblame scan, blame, and fix terminal demo](docs/assets/blame-demo.gif)
+
+## Install
+
+```console
+uv tool install mojiblame     # or: pipx install mojiblame
+```
+
+## Use
+
+```console
+mojiblame scan [PATH]     read-only report, with the standard of proof for each finding
+mojiblame blame <FILE>    which commit broke it, which step, what history can restore
+mojiblame fix [PATH]      apply only the provable fixes; --dry-run, --yes
+mojiblame undo            restore the originals from the last fix
+mojiblame guard [PATH]    exit non-zero if anything is corrupted (CI, hooks)
+mojiblame init            wire it into pre-commit, GitHub Actions, or your agent
+```
+
+`fix` journals the original bytes before it changes anything, so `undo` is byte-identical —
+not "close enough". Inside a git repo, scanning honours `.gitignore`.
+
+## Wire it in
+
+**pre-commit** — the version most people should use, because it runs without anyone remembering it:
+
+```yaml
+repos:
+  - repo: https://github.com/Golemozan/mojiblame
+    rev: v0.1.0
+    hooks:
+      - id: mojiblame
+```
+
+**GitHub Actions** — `mojiblame init --github`, or:
+
+```yaml
+- run: pip install mojiblame
+- run: mojiblame guard .
+```
+
+**Coding agents** — `mojiblame init --claude` installs a `PreToolUse` hook that inspects writes
+*before they reach the disk* and blocks the ones that would introduce corruption. Cleaning up
+afterwards is the losing half of this problem; the agent is told what it was about to corrupt
+and can retry correctly:
+
+```
+mojiblame blocked this write to notes.md: mojibake (cp1254 -> utf-8, 1 layer(s)).
+The text was decoded with the wrong codec somewhere upstream.
+Intended text starts: 'yönetici İŞ şğüöç'
+```
+
+## Suppression
+
+Some files contain broken characters on purpose — documentation about encoding bugs, test
+fixtures, golden files. Two ways to say so:
+
+```gitignore
+# .mojiblameignore
+fixtures/
+*.snapshot
+```
+
+or put `mojiblame:ignore-file` anywhere in the file. The marker is matched against raw bytes,
+so it still works in files that do not decode cleanly — which is exactly where you need it.
+
+## Limitations
+
+Stated plainly, because a forensics tool that oversells itself is worse than none:
+
+- **Codec identification is statistical.** `latin-1` decodes every possible byte sequence, so a
+  clean round-trip proves the transcode is reversible, not that the codec was right. mojiblame
+  reports those as two separate facts and never merges them into one confident claim.
+- **The codec *name* on a mojibake finding may be one of several.** Where two codepages map the
+  characters in a file identically, they are indistinguishable from the bytes — corruption caused
+  by cp1254 is reported as `latin-1 -> utf-8` when the text contains nothing that separates them.
+  The recovered text is the same either way, and it is the part that gets verified; only the label
+  is ambiguous.
+- **Destroyed characters with no clean ancestor stay destroyed.** If a line was first written
+  already broken, no earlier version exists and mojiblame will tell you it recovered `0 / n`
+  rather than inventing text.
+- **History walking assumes damage, once introduced, persists.** That assumption is verified,
+  and the search falls back to a linear scan when a file was broken, fixed, and broken again.
+- Files over 5 MB are skipped by default.
+
+## How it works
+
+```
+detect/facts.py       BOM, line endings, strict UTF-8 decode - facts, no inference
+detect/codecs.py      D1: which legacy codec, and is the transcode reversible
+detect/mojibake.py    D2: repair plan, layer depth, and the inverse-plan proof
+gitfx/repo.py         git, always via bytes - never text=True, never the console codepage
+gitfx/forensics.py    binary-searches history for the commit that introduced the damage
+gitfx/recover.py      splices destroyed runs from the clean version, keeping later edits
+fixing/journal.py     gzipped originals so undo is byte-identical
+hooks/                pre-commit entry point and the agent PreToolUse guard
+```
+
+One detail worth calling out: `gitfx/repo.py` never uses `subprocess(text=True)`. That decodes
+with the console codepage — cp1254 on a Turkish Windows box — which is precisely the bug class
+this tool hunts. A forensics tool that mangles its own evidence is worthless, so every git call
+returns bytes and decoding is always an explicit, local decision.
+
+## Why this exists
+
+A memory system I run injected context into every session for months. It was writing `y���n�`
+where it meant `yönetici`, and nothing ever failed — the sessions just quietly got a little
+worse. The cause was a PowerShell 5.1 hook writing stdout in the console codepage.
+
+Finding it took an afternoon. Knowing *when* it started took git archaeology by hand, and by
+then the answer to "can any of this be recovered?" was pure guesswork. mojiblame is that
+afternoon, made repeatable.
+
+Its first real run, against that same 437-file vault, found four damaged files and named the
+commit responsible for each.
+
+## License
+
+MIT

mojiblame-0.1.0/docs/assets/pipeline.svg

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="430" viewBox="0 0 1400 430" role="img" aria-labelledby="title desc">
+  <!-- mojiblame:ignore-file — the final node intentionally shows a mojibake sample. -->
+  <title id="title">How silent encoding corruption enters a repository</title>
+  <desc id="desc">A UTF-8 file is read by an agent or tool through a shell, decoded with the wrong codepage, and written back as mojibake. Every step reports success.</desc>
+  <defs>
+    <linearGradient id="panel" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#10171c"/>
+      <stop offset="1" stop-color="#080c0f"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#000" flood-opacity=".28"/>
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#93a1aa"/>
+    </marker>
+    <style>
+      .label { font: 700 14px ui-monospace, SFMono-Regular, Consolas, monospace; letter-spacing: .12em; fill: #ffab00; }
+      .title { font: 700 21px ui-monospace, SFMono-Regular, Consolas, monospace; fill: #edf1f3; }
+      .body { font: 400 16px ui-monospace, SFMono-Regular, Consolas, monospace; fill: #aeb9bf; }
+      .code { font: 600 18px ui-monospace, SFMono-Regular, Consolas, monospace; fill: #edf1f3; }
+      .arrow-label { font: 600 13px ui-monospace, SFMono-Regular, Consolas, monospace; fill: #7f8c94; letter-spacing: .08em; }
+    </style>
+  </defs>
+
+  <rect x="1" y="1" width="1398" height="428" rx="18" fill="url(#panel)" stroke="#34424a" stroke-width="2"/>
+  <text x="54" y="51" class="label">THE SILENT CORRUPTION PATH</text>
+  <text x="1346" y="51" text-anchor="end" class="body">deterministic · no inference</text>
+
+  <g filter="url(#shadow)">
+    <g transform="translate(54 92)">
+      <rect width="260" height="176" rx="13" fill="#121b20" stroke="#44535b"/>
+      <text x="24" y="36" class="label">01 · FILE</text>
+      <text x="24" y="76" class="title">UTF-8 on disk</text>
+      <rect x="24" y="100" width="212" height="48" rx="7" fill="#080c0f" stroke="#2c3940"/>
+      <text x="42" y="131" class="code">yönetici</text>
+    </g>
+
+    <g transform="translate(397 92)">
+      <rect width="260" height="176" rx="13" fill="#121b20" stroke="#44535b"/>
+      <text x="24" y="36" class="label">02 · READ</text>
+      <text x="24" y="76" class="title">agent / tool</text>
+      <text x="24" y="111" class="body">shell</text>
+      <text x="24" y="140" class="body">subprocess stdout</text>
+    </g>
+
+    <g transform="translate(740 92)">
+      <rect width="260" height="176" rx="13" fill="#1c1710" stroke="#ffab00" stroke-width="2"/>
+      <text x="24" y="36" class="label">03 · DECODE</text>
+      <text x="24" y="76" class="title">wrong codepage</text>
+      <text x="24" y="113" class="code">cp1254</text>
+      <text x="24" y="143" class="body">bytes ≠ characters</text>
+    </g>
+
+    <g transform="translate(1083 92)">
+      <rect width="260" height="176" rx="13" fill="#121b20" stroke="#44535b"/>
+      <text x="24" y="36" class="label">04 · WRITE BACK</text>
+      <text x="24" y="76" class="title">valid UTF-8</text>
+      <rect x="24" y="100" width="212" height="48" rx="7" fill="#080c0f" stroke="#ffab00"/>
+      <text x="42" y="131" class="code" fill="#ffbf3f">yönetici</text>
+    </g>
+  </g>
+
+  <g fill="none" stroke="#93a1aa" stroke-width="2" marker-end="url(#arrow)">
+    <path d="M 320 180 H 381"/>
+    <path d="M 663 180 H 724"/>
+    <path d="M 1006 180 H 1067"/>
+  </g>
+  <text x="350" y="164" text-anchor="middle" class="arrow-label">READ</text>
+  <text x="693" y="164" text-anchor="middle" class="arrow-label">TEXT</text>
+  <text x="1036" y="164" text-anchor="middle" class="arrow-label">WRITE</text>
+
+  <rect x="54" y="309" width="1289" height="76" rx="12" fill="#18140c" stroke="#ffab00" stroke-width="2"/>
+  <circle cx="91" cy="347" r="17" fill="#ffab00"/>
+  <path d="M 91 335 V 351 M 91 361 V 362" stroke="#111" stroke-width="4" stroke-linecap="round"/>
+  <text x="126" y="341" class="title">NO STEP THROWS AN ERROR.</text>
+  <text x="126" y="369" class="body">Read succeeds. Decode succeeds. Write succeeds. The silence is the bug.</text>
+</svg>