# Používateľský manuál: ITHZ-MCP

ITHZ-MCP je lokálna projektová pamäť pre AI agentov. Ukladá rozhodnutia,
gates, riziká, workflow pravidlá, scoped claims, blocked claims, prompt
summary a ďalšie auditovateľné záznamy do súboru `project.ithz`.

Krátka veta:

```text
Markdown je bootstrap. ITHZ je pamäťová zóna.
```

To znamená:

- `project.md` je krátky ľudsky čitateľný štartovací návod pre agenta;
- `project.ithz` je dlhodobá deterministická pamäť projektu;
- Git stále ostáva zdroj histórie kódu;
- ITHZ-MCP nie je produkčná databáza, cloud sync ani náhrada Gitu.

## Kedy ho použiť

Použi ITHZ-MCP, keď chceš, aby si agent pamätal:

- ako má projekt čítať a meniť;
- ktoré rozhodnutia už padli;
- ktoré claims sú povolené iba v úzkom rozsahu;
- ktoré claims sú blokované;
- aké testy/gates musia prejsť;
- čo sa spravilo v poslednom tasku;
- aké riziká alebo must-not-break pravidlá platia;
- aké sú ďalšie kroky.

Nepoužívaj ho ako:

- úložisko tajomstiev;
- backup zdrojových súborov;
- náhradu review;
- náhradu deploy systému;
- univerzálnu RAG/vector databázu.

## Základné súbory v projekte

Bežný projekt má:

```text
project.md
project.ithz
```

`project.md` má byť krátky. Typicky obsahuje:

- čo je projekt;
- ako má agent začať;
- ktoré docs sú zdroj pravdy;
- čo sa nesmie tvrdiť alebo robiť;
- ako sa má ukončiť task.

`project.ithz` obsahuje archive memory vrstvy:

- `events/events.jsonl`;
- `indexes/current_index.json`;
- `indexes/memory_synthesis.json`;
- `claims/claim_log.jsonl`;
- `claims/blocked_claim_log.jsonl`;
- `replication/replication_pack_log.jsonl`;
- `review/reviewer_notes.jsonl`;
- `ledger/project_ledger_summary.json`.

Tieto vnútorné súbory normálne neupravuješ ručne. Pracuješ cez CLI alebo MCP
tools.

## Predpoklady

V tomto repozitári sa CLI spúšťa takto:

```powershell
$env:PYTHONPATH='C:\work\ITHKOR\ithz_mcp\src'
python -m ithz_mcp version
```

Ak používaš nainštalovaný balík, `PYTHONPATH` nemusí byť potrebný.

Native archive režim potrebuje `ithz-native.exe`. ITHZ-MCP ho vyberá v tomto
poradí:

1. `--native-exe <path>`;
2. premenná `ITHZ_NATIVE_EXE`;
3. auto výber AVX2/scalar binárky z balíka alebo repozitára.

Overenie:

```powershell
python -m ithz_mcp archive-memory-status --project .
```

Vo výstupe hľadaj:

- `exists`;
- `active_memory_zone`;
- `safe_verify_ok`;
- `native_exe`;
- `native_selected_build`;
- `index_mode`.

## Inštalácia do projektu

Najprv si pozri dry-run plán:

```powershell
python -m ithz_mcp install-project --project C:\work\my_project
```

Skutočná inštalácia:

```powershell
python -m ithz_mcp install-project `
  --project C:\work\my_project `
  --apply `
  --profile gobi `
  --owner "Gobi" `
  --index-mode compact-v2
```

Čo to spraví:

- vytvorí alebo overí `project.md`;
- vytvorí alebo overí `project.ithz`;
- nastaví workflow profil;
- ak je projekt v Gite, pridá ITHZ-aware diff/merge driver;
- nepúšťa `git add`, `git commit`, `git push`;
- nezapisuje secrets.

Ak chceš zároveň pridať Codex host config:

```powershell
python -m ithz_mcp install-project `
  --project C:\work\my_project `
  --apply `
  --profile gobi `
  --owner "Gobi" `
  --install-codex-config
```

Ak chceš importovať lokálnu agent históriu:

```powershell
python -m ithz_mcp install-project `
  --project C:\work\my_project `
  --apply `
  --profile gobi `
  --owner "Gobi" `
  --import-agent-history `
  --history-source codex
```

Pri veľkej histórii počítaj s tým, že secret-like časti môžu byť blokované.
Vtedy radšej importuj menší sanitizovaný subset namiesto surového brute-force
importu.

## Bežný začiatok práce

Keď agent alebo človek začne task:

1. Otvorí projekt.
2. Prečíta `project.md`.
3. Skontroluje stav pamäte.
4. Vyžiada si kontextový balík pre konkrétnu úlohu.
5. Až potom číta súbory, ktoré kontextový balík odporučí.

Príkazy:

```powershell
python -m ithz_mcp archive-memory-status --project .

New-Item -ItemType Directory -Force -Path .\.ithz-install\tmp | Out-Null

python -m ithz_mcp archive-get-context-pack `
  --project . `
  --query "oprav chybu v auth flow a skontroluj bezpečnostné pravidlá" `
  --max-bytes 12000 `
  --out .\.ithz-install\tmp\ithz_context_pack.md
```

Vyhľadanie v pamäti:

```powershell
python -m ithz_mcp archive-search-context `
  --project . `
  --query "deployment gates risks" `
  --limit 10
```

## Bežný koniec práce

Po dokončení netriviálneho tasku zapíš checkpoint.

CLI fallback:

```powershell
python -m ithz_mcp archive-finalize-task `
  --project . `
  --task "Fix auth redirect" `
  --summary-text "Opravené presmerovanie po login-e a overené smoke testom." `
  --decision "Decision: redirect target is validated before use." `
  --gate "Gate: auth smoke passed." `
  --risk "Risk: do not store tokens in project.ithz." `
  --next "Next: add browser-level regression test." `
  --docs-impact updated `
  --memory-impact handoff-created `
  --snapshot `
  --snapshot-mode auto
```

V MCP hoste je preferovaný write-enabled nástroj:

```text
ithz_archive_auto_checkpoint
```

Používa sa na konci tasku s názvom tasku, summary, decisions, gates, risks,
next steps, changed files a commands.

Pri veľkom archíve môže vrátiť:

```text
queued=true
```

To znamená, že zápis beží v lokálnom background workeri. Sleduj vrátený
`job_log`, ak potrebuješ potvrdiť dokončenie.

## Read-only MCP režim

Read-only režim je bežný režim pre agentov:

```powershell
python -m ithz_mcp mcp-server `
  --project C:\work\my_project `
  --mode read-only `
  --protocol mcp `
  --storage-profile native-archive
```

Typické read-only tools:

- `ithz_context_status`;
- `ithz_archive_status`;
- `ithz_archive_search_context`;
- `ithz_archive_get_context_pack`;
- `ithz_workflow_profile_status`;
- `ithz_workflow_context_pack`;
- `ithz_list_allowed_claims`;
- `ithz_list_blocked_claims`;
- `ithz_get_claim_evidence`;
- `ithz_can_i_claim`.

Read-only profil nezapisuje do `project.ithz`.

## Write-enabled MCP režim

Write-enabled režim používaj len vedome, najmä na konci tasku:

```powershell
python -m ithz_mcp mcp-server `
  --project C:\work\my_project `
  --mode write-enabled `
  --protocol mcp `
  --storage-profile native-archive
```

Typické write-enabled tools:

- `ithz_archive_auto_checkpoint`;
- `ithz_archive_append_event`;
- `ithz_record_workflow_rule`;
- `ithz_record_project_decision`;
- `ithz_record_gate_rule`;
- `ithz_record_risk_rule`;
- `ithz_add_claim`;
- `ithz_block_claim`;
- `ithz_add_reviewer_note`;
- `ithz_create_replication_pack_record`.

Write-enabled režim nie je určený na neviditeľné priebežné mutácie. Zápisy
majú byť explicitné a auditovateľné.

## Project Ledger

Project Ledger je auditná kniha vo vnútri `project.ithz`.

Ukladá:

- scoped claims;
- blocked claims;
- replication pack records;
- reviewer notes.

Overenie, či môžeš niečo tvrdiť:

```powershell
python -m ithz_mcp ithz-can-i-claim `
  --project . `
  --claim "ITHKOR proves gravity"
```

Pridanie scoped claimu:

```powershell
python -m ithz_mcp ithz-add-claim `
  --project . `
  --claim-id claim_special_ithkor_finite_qpu `
  --text "Special ITHKOR has scoped finite/QPU diagnostic support." `
  --scope finite/qpu `
  --supporting-gate D20 `
  --status allowed_scoped
```

Zablokovanie claimu:

```powershell
python -m ithz_mcp ithz-block-claim `
  --project . `
  --claim-id blocked_gravity_claim `
  --text "ITHKOR proves gravity" `
  --reason "No physical D claim is authorized by current gates." `
  --blocking-gate D20
```

Súhrn ledgeru:

```powershell
python -m ithz_mcp ithz-get-project-ledger-summary --project .
```

## Workflow profily

Workflow profil je sada pravidiel pre konkrétneho človeka alebo režim práce.

Vytvorenie alebo adopcia profilu:

```powershell
python -m ithz_mcp archive-adopt-project-workflow `
  --project . `
  --profile gobi `
  --owner "Gobi" `
  --prompt C:\work\tmp\project_onboarding.md
```

Aktualizácia profilu:

```powershell
python -m ithz_mcp workflow-ingest-prompt `
  --project . `
  --profile gobi `
  --owner "Gobi" `
  --prompt C:\work\tmp\updated_workflow.md `
  --set-default
```

Kontext podľa profilu:

```powershell
python -m ithz_mcp workflow-context-pack `
  --project . `
  --profile gobi `
  --query "deployment workflow and validation gates" `
  --max-bytes 12000 `
  --out C:\work\tmp\workflow_pack.md
```

## Prompt memory

Predvolený bezpečný režim je `summary`.

Zápis prompt/response summary:

```powershell
python -m ithz_mcp archive-record-prompt-response `
  --project . `
  --prompt C:\work\tmp\prompt.md `
  --response C:\work\tmp\response.md `
  --task "Investigated production issue" `
  --mode summary
```

Vyhľadanie:

```powershell
python -m ithz_mcp archive-search-context `
  --project . `
  --query "Investigated production issue" `
  --limit 10
```

Režimy:

- `summary`: bezpečný default, summary + hash;
- `full-redacted`: uloží redigovaný obsah;
- `full-local-only`: explicitne lokálne, preskakuje team sync/merge output.

## Memory zones

Predvolené správanie:

```text
--memory-zone nearest
```

ITHZ-MCP hľadá najbližší `project.ithz` od `--project` smerom nahor.

Použitie parent zóny:

```powershell
python -m ithz_mcp archive-get-context-pack `
  --project C:\repo\subproject `
  --memory-zone parent `
  --query "parent project deployment rules" `
  --max-bytes 12000
```

Použitie explicitnej zóny:

```powershell
python -m ithz_mcp archive-get-context-pack `
  --project . `
  --memory-zone-path C:\work\ITHKOR\native_ithz `
  --query "native archive safety gates" `
  --max-bytes 12000
```

Pre úlohy, ktoré sa dotýkajú viacerých zón:

```powershell
python -m ithz_mcp archive-link-zone `
  --project . `
  --zone native_ithz `
  --path C:\work\ITHKOR\native_ithz `
  --relationship sibling

python -m ithz_mcp archive-cross-zone-context-pack `
  --project . `
  --query "changes touching ithz_mcp and native_ithz" `
  --max-bytes 16000
```

## Git integrácia

ITHZ-MCP dopĺňa Git. Nenahrádza ho.

Nainštalovanie ITHZ-aware diff/merge drivera:

```powershell
python -m ithz_mcp install-git-drivers --repo . --dry-run
python -m ithz_mcp install-git-drivers --repo .
```

Stable text diff pre `project.ithz`:

```powershell
python -m ithz_mcp git-diff-ithz --archive project.ithz
```

Merge troch archívov:

```powershell
python -m ithz_mcp git-merge-ithz `
  --base base.ithz `
  --ours ours.ithz `
  --theirs theirs.ithz `
  --out merged.ithz
```

Merge driver vie zjednotiť nezávislé append-only udalosti. Pri konflikte vráti
`merge_needed` a report.

## Čo commitovať

Typicky commituj:

```text
project.md
project.ithz
.gitattributes
```

Typicky necommituj:

```text
.ithz-install/
dočasné context packy
host smoke transcript súbory
privátne lokálne prompt logy
```

Host configy commituj len vtedy, keď to tím chce a cesty sú skontrolované.

## Bezpečnostné pravidlá

ITHZ-MCP ignoruje alebo blokuje:

- `.env`;
- private keys;
- tokeny;
- credential-like text;
- secret-like file names;
- build/cache/vendor výstupy;
- existujúce `.ithz` archívy pri zdrojovom snapshot režime.

Ak narazíš na `secret_like_*_blocked`, nesnaž sa obísť ochranu. Vytvor
sanitizovaný summary alebo menší bezpečný vstup.

## Troubleshooting

Skontroluj verziu:

```powershell
python -m ithz_mcp version
```

Skontroluj archive status:

```powershell
python -m ithz_mcp archive-memory-status --project .
```

Ak native exe chýba:

```powershell
$env:ITHZ_NATIVE_EXE="C:\path\to\ithz-native.exe"
```

Ak host nevidí MCP tools:

```powershell
python -m ithz_mcp mcp-config-validate --config .\.ithz-install\host_installers\codex_mcp_config.sample.json
python -m ithz_mcp mcp-client-smoke --config .\.ithz-install\host_installers\codex_mcp_config.sample.json
```

Ak checkpoint vráti `queued=true`, skontroluj `job_log`. Pri veľkých archívoch
je async zápis očakávané správanie.

## Odinštalovanie

Dry-run:

```powershell
python -m ithz_mcp uninstall-project
```

Skutočné odstránenie:

```powershell
python -m ithz_mcp uninstall-project --apply
```

Zachovanie bootstrapu:

```powershell
python -m ithz_mcp uninstall-project --apply --keep-project-md
```

Zachovanie host configov:

```powershell
python -m ithz_mcp uninstall-project --apply --keep-host-configs
```

## Najkratší denný checklist

Začiatok:

```powershell
Get-Content project.md
python -m ithz_mcp archive-memory-status --project .
python -m ithz_mcp archive-get-context-pack --project . --query "<task>" --max-bytes 12000
```

Koniec:

```powershell
python -m ithz_mcp archive-finalize-task --project . --task "<task>" --summary-text "<summary>" --docs-impact updated --memory-impact handoff-created
git status --short
```

