feat(fileshare): a skill for the file tool

[sauterbe]

Why

xentral_fileshare is the one heavily-used tool with no skill: its guidance is a legacy in-repo guide in the backend (backend/files/agent_guide/{en,de}.md), served only because agent_guides.loader falls back for domains without a skill.

That is why the single most important fact at this boundary had nowhere to live and ended up in the datasets skill's CSV-import phase 0 (#73): a file the user attached in the chat is already in the drive, and the agent already holds its file_key. In datasets it only covers CSVs — the same is true of a PDF, a log or an xlsx, and the two tools are otherwise independent (datasets = create and maintain data tables, fileshare = plain file exchange).

What is in it

skills/xentral-fileshare/SKILL.md (143 lines) + reference/recipes-and-pitfalls.md (82).

The parts that are new rather than ported:

• "A file the user attached is already in here", with the two failures it prevents: asking the user to upload a file they just attached, and saying a file was "too large to receive" — nothing is too large to receive; what is too large to inline arrives as a key plus a labelled sample. Plus the rule that follows: never answer a "how many / how much" from a sample.
• The boundary to xentral_datasets, stated as the expensive mistake it is: the moment a figure is wanted, the file belongs to import_analyze (every row, a few KB back) — including for a small table.
• What the tool cannot do, with the route to take instead: no windowed read, no search inside a file, no in-place edit, no folders, no versions, no xlsx extraction. An agent that knows the limit stops at a dead end less often than one that discovers it mid-answer. (These are the gaps planned in xentral/agent-os → docs/plans/file-tools-for-the-model.md; when they land, this table shrinks.)
• The source values as they now are — chat, inbox, slack, advisor, api — which the legacy guide predates.

Ported and tightened from the legacy guide: purpose and non-purposes, the concepts table, the action reference, the rules that bite (tenant isolation, content XOR content_b64, irreversible delete, filenames are not unique), the recipes and the pitfalls table.

Verification

• Assembled through the real backend loader (agent_guides.loader._assemble_skill against this directory): 10 651 characters, frontmatter stripped, reference folded in at the right place, _parse_frontmatter reads name + description + 3 examples — so action='help', the Advisor overlay, the in-app guide and the plugin all serve it.
• python scripts/validate_library.py → OK: 337 library items valid against their schemas.
• manifest.json still parses; SKILL.md is well under the 500-line guideline.

Two things to know

manifest.json's skills array was missing xentral-datasets (8 entries for 9 skills). Both it and the new skill are added, so the array is truthful again — 10 for 10. I could find no consumer of that array in the backend (the sync copies directories, the loader resolves by path), so this is an index fix on its own; if the customer plugin reads it, datasets was invisible there until now.

Wiring is a follow-up in the backend repo, not here: _DOMAIN_TO_SKILL["fileshare"] = "xentral-fileshare" plus _DOMAIN_TO_TOOL, a LIBRARY_VERSION bump, and deleting the legacy backend/files/agent_guide/. Worth flagging in that PR: skills are English-only today, so registering this one drops the German version of this guide (load_guide(locale='de') returns the assembled English skill for skill-backed domains). That is the existing convention for every other skill, not a new decision — but it is a visible change for this domain, so it should be a conscious one rather than a side effect.