docs(m1): correct the install block for external adopters

The install block was written under the assumption that this project has no
users but its author. It has two, so every claim in it is now load-bearing.

Three corrections, each measured rather than reasoned:

- The guard's host is reachable. `git.fromaitochitta.com` resolves to a public
  address, serves a valid certificate and answers `git ls-remote` with no
  credentials, no global git config and no terminal prompt; a non-existent
  repository on the same host fails, so the query can distinguish. A full
  anonymous `pip install` of the pinned `v1.3.0` builds a wheel and imports at
  1.3.0. The old text told a third party they probably could not reach it.
- The Claude Code route did not work. `claude plugin install` resolves only
  through a marketplace and `jobbsok` is not among the catalog's twelve
  plugins, so the documented command failed at its first step. It is marked as
  landing with milestone 2 instead of being printed as if it worked.
- Windows is named as unsupported, with the specific reason: the entry points
  are shell scripts and `.mcp.json` starts the tool server through `bash`. The
  Python underneath is already platform-clean, so the gap is packaging.

Prerequisites are stated up front, with a preflight command that needs nothing
installed, because an adopter should learn about a blocked network before
building a virtualenv rather than after.

Outside Step 16's Files list, and so a separate commit rather than part of the
pinned Cowork-verification commit, following the precedent of 90ef620.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-05 20:11:13 +02:00
commit c2ee7b6788

View file

@ -23,27 +23,34 @@ ingestion, correspondence, drafting and learning are not. The build brief in
## Install ## Install
Read this first if you are not the author. The ingestion guard this plugin **Prerequisites.** Python 3.10 or newer -- the host tool server refuses to start
depends on is installed from a **self-hosted** Forgejo host, below that rather than serving on an interpreter the guard cannot run on --
`git.fromaitochitta.com`, which a third party may not be able to reach. This `git` on `PATH`, and network access to `git.fromaitochitta.com`, the self-hosted
repository is published as a working reference, not as a one-command install: Forgejo host the ingestion guard is installed from. That host is public and
if you cannot reach that host, everything here is readable and most of it needs no account. One command tells you whether your network agrees, and it
runs, but the guarded ingestion path cannot be built. Saying so plainly is needs nothing else installed:
better than an install block whose first step fails for everyone but its
author. ```bash
git ls-remote https://git.fromaitochitta.com/open/llm-ingestion-pipeline-security.git v1.3.0
```
A printed hash means the guarded ingestion path will build. An error means it
will not, and that is not a cosmetic loss: the guard is the boundary every
untrusted listing and email body passes at the write, so an install without it
is a reader rather than a workspace.
**Platform support.** macOS and Linux work today. **Windows does not yet**, and
the reason is specific rather than general: this plugin's entry points are shell
scripts and `.mcp.json` starts the tool server through `bash`, which stock
Windows does not have. The Python underneath is already platform-clean, so this
is a packaging gap being closed rather than a rewrite. Until it is closed,
Windows needs a POSIX shell (WSL or Git Bash) and is not a supported target.
The plugin runs on two surfaces, and they install differently. The plugin runs on two surfaces, and they install differently.
**Claude Code** — pinned by tag in the `ktg-plugin-marketplace` catalog: **Claude Cowork** -- the route that works today. There is no marketplace command:
build the archive from this repository's explicit include list, then upload it
```bash through *Customize -> Plugins*:
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
claude plugin install jobbsok@ktg-plugin-marketplace
```
**Claude Cowork** — there is no marketplace command. Build the archive from
this repository's explicit include list, then upload it through
*Customize → Plugins*:
```bash ```bash
bash scripts/package_plugin.sh # writes jobbsok.plugin bash scripts/package_plugin.sh # writes jobbsok.plugin
@ -53,8 +60,16 @@ Never build that archive with a recursive zip of the repository root: it would
ship `.git`, the virtualenv, the local-only `STATE.md` and everything under ship `.git`, the virtualenv, the local-only `STATE.md` and everything under
`.claude/`. The script exists so that cannot happen by accident. `.claude/`. The script exists so that cannot happen by accident.
**Then, once, on either surface** — build the Python environment the scripts **Claude Code** -- not available yet. `jobbsok` is deliberately absent from the
and the host tool server run on: `ktg-plugin-marketplace` catalog while it is pre-release, and `claude plugin
install` resolves only through a marketplace, so no command here would work
today. The catalog entry lands with milestone 2, pinned to a release tag.
Printing an install line that fails at its first step would be worse than
saying so.
**Then, once, on either surface** -- build the Python environment the scripts
and the host tool server run on. This is also the step that installs the
ingestion guard, and it prints the version it resolved:
```bash ```bash
bash scripts/bootstrap.sh # add --med-xlsx for the spreadsheet export bash scripts/bootstrap.sh # add --med-xlsx for the spreadsheet export
@ -67,7 +82,7 @@ virtualenv, so the bootstrap is the supported route there. Without it the
rather than serving on whatever `python3` the PATH offers. `JOBBSOK_PYTHON` rather than serving on whatever `python3` the PATH offers. `JOBBSOK_PYTHON`
overrides the interpreter choice. overrides the interpreter choice.
**Finally, the workspace** — the plugin never guesses at a location: **Finally, the workspace** -- the plugin never guesses at a location:
```bash ```bash
export JOBBSOK_WORKSPACE=~/jobbsok-workspace # or pass --workspace export JOBBSOK_WORKSPACE=~/jobbsok-workspace # or pass --workspace