[kalwei]

What this is

One download, fsmes-assistant.zip, that a person hands to whatever AI
assistant they already use — Claude, ChatGPT, Copilot, a local model, in a chat
window in the cloud or on the box — and says "help me install
FactorySemantics MES". It is plain markdown and nothing else. The agent needs
no access to the machine: the person runs every command and pastes back what it
printed.

Four stages, one at a time:

1. Install — Windows words first, because that is where the first person
   was — until fsmes demo bottling answers on 127.0.0.1:8010.
2. A plant shaped like yours — the existing plant-from-your-mes folder,
   nested inside this one as stage 2, ending at fsmes demo from-shape.
3. Shadow mode beside your MES — docs/operate/first-plant.md turned into
   an agent's script, ending at the shadow scorecard.
4. Migration — what you have when the scorecard matches, what is not
   built, and how to tell us. It stops there. No commands on that page.

It comes out of an installation with no download and no internet:

fsmes skills unpack assistant ./assistant

The boring piece first: the folder cannot drift from the CLI

tests/test_every_command_the_assistant_folder_tells_you_to_run_exists.py
pulls every fsmes … command out of the markdown — inline code spans and
shell-ish fenced blocks, \ continuations folded, py -m fsmes and
.venv\Scripts\fsmes spellings included — and resolves each one against the
typer app: sub-command by sub-command, then the options, then the number of
arguments. 59 commands across the pages today (23 of them in 1-install.md), and 4-migration.md deliberately carries none.

Proof it goes red, from breaking one command in 1-install.md:

$ sed -i 's/fsmes demo bottling/fsmes demmo bottling/' skills/assistant/1-install.md
$ pytest 'tests/test_every_command_the_assistant_folder_tells_you_to_run_exists.py::\
test_every_fsmes_command_on_this_page_resolves_against_the_cli[1-install.md]'

E  AssertionError: 1-install.md: `fsmes demmo bottling status` — `fsmes` has no
E  sub-command 'demmo'. It has: add-user, agent-eval, ai, ai-status, assist,
E  autoloop, backup, config-audit, db-status, demo, design-backlog, design-log…

$ sed -i 's/--buffer 20/--bufer 20/' skills/assistant/2-your-plant.md

E  AssertionError: 2-your-plant.md: `fsmes shape plant plant-shape.toml --out
E  ./acme --bufer 20` — `fsmes shape plant` has no option '--bufer'. It has:
E  --buffer, --force, --help, --hours, --name, --out, --seed

What it cannot catch is written down in the test itself
(test_what_this_check_cannot_catch_is_written_down): an argument's value is
not a CLI name, so fsmes demo bottling stattus is well-formed as far as click
is concerned. A page quoting computer output must label its fence text, or the
check reads the output as input — also written down, and
test_output_quoted_on_a_page_is_not_read_as_a_command holds it.

One copy in git, nested at build time

Stage 2 is plant-from-your-mes, so that folder has to be inside the one a
person downloads. It is not a second copy in git and it is not a symlink — a
zipped symlink arrives on Windows as a text file with a path in it. The
relationship is one line of registry, fsmes.skills.INCLUDES, which
build_zip and unpack both read, so the nesting is made from the single copy
in skills/plant-from-your-mes/. Two tests hold that: the folder has no
skills/assistant/plant-from-your-mes in it, and nothing anywhere in it is a
symlink.

The two names. The skill is called assistant — that is what a person
types after fsmes skills unpack. The download and the top-level folder inside
the zip are called fsmes-assistant, because a zip lands in a folder beside
other people's downloads and has to say whose it is. One dict,
fsmes.skills.RELEASED, says which skills a release attaches and under what
name, and the release workflow loops that instead of SKILLS.
plant-from-your-mes.zip is retired from the upload list — it is inside this
one now; two downloads of the same files would be a question about which to
take. The skill itself stays in SKILLS: still checked, still unpackable by
name, and fsmes shape plant's hint text still names it.

Checked

• .github/scripts/assistant_folder_from_the_wheel.py, a first step in the
  existing wheel-plant-from-shape job so no new Windows leg is paid for: a
  fresh venv with the built wheel, the network off, fsmes skills list names
  assistant, fsmes skills unpack assistant ./x writes 48 files with
  plant-from-your-mes/ among them, every one byte-for-byte the checkout's,
  no symlink anywhere. Ran green here on Linux; Windows is this PR's job.
• fsmes skills-zip --check now covers every skill and each skill's includes;
  CI runs it bare.
• The zip's contents, the page lengths (each stage page under 200 lines, the
  folder outside plant-from-your-mes/ 824 lines), and the page-one rules
  being the first thing in SKILL.md all have tests.
• ruff check . clean; the default pytest tier green.

Honest caveats

• Nobody has run shadow mode on a real plant. first-plant.md is written
  and untried, and stage 3 says so in its own footer rather than only here.
• What the agent will get wrong. It will be confident about the stage it is
  reading and vague about the rest; it cannot see the person's screen, so a
  command that half-worked reads to it as a command that worked unless the
  person pastes the whole output; it will not know which of the five rules it
  is breaking if its own system prompt tells it to be helpful by running
  things. The rules are first in the file for that reason, and 0-how-to-help.md
  tells it to name the page it is reading from when it is unsure.
• What the folder cannot know. Anything about their plant: their OPC
  security policy, whether their IT department will trust a certificate, what
  their MES calls its tables, whether their 0.3.0 install is the one the page
  describes. Every "what the output means" section is the three or four things
  that actually went wrong for the one person who has done this, plus what the
  code prints today.
• Stage 4 says no. Asked "can I switch my old MES off now?", the folder's
  answer is no, with the list of what is missing — cutover, history migration,
  PLC write-back beyond the recommendation queue, confirmations to an ERP in
  charge, and the plain fact that none of this has run in production.
• Not done here, and the handoff says it is the steward's: the live run with a
  fresh assistant, the zip uploaded, somebody playing the first user on
  Windows. That is the real test of a folder like this and it has not happened
  yet.

No release in this PR. CHANGELOG.md ## [Unreleased] carries the line.

After the steward's live run

The steward ran this before merge the way it is meant to be used: a fresh
no-tools assistant, the seven pages pasted in as the zip, him playing the first
user on Windows 11. It passed — one command per turn, the paste asked for, the
production data pasted "in case it helps" refused, taskkill for the half-dead
plant, and a plain no to "can we switch the old MES off". It found one real
gap, now fixed in 1-install.md and 0-how-to-help.md: the cheapest way out
of not recognized is py -m fsmes, which arrived in #172 and ships in 0.3.1,
so on 0.3.0 — the only release anybody has — it prints No module named fsmes.__main__. The page says that now, and the two places that used
fsmes --version to settle "is it installed at all" use
py -m pip show factorysemantics-mes, which answers with PATH broken or not.

[github-actions]

Thanks for the first pull request. Checks: every commit signed off (git commit -s), ruff and pytest green, and the house-rules checklist in the template. The maintainer reviews within a few days.