feat(sources v1): the agent locates files itself — ls/find/grep + tool-call cards

User pivot (2026-09-19): no attachments UI at all. Pasting paths is native
for technical users and alien for everyone else - so the agent gets the
tools to find what the learner merely NAMES. The learner communicates in
messages; the agent locates and reads. Zero cross-stream seams: paths
already live in tool parts, so the sources "list" is the transcript.

- ls/find/grep: pi-verbatim schemas, descriptions, and output formats
  (fd's glob semantics, rg's path:line: match format, pi's truncation
  notices), ported to pure Node - no binaries, no shell-out, read-only by
  construction. Deltas from pi: home-anchored resolution (the harness has
  no cwd), .gitignore replaced by hard noise exclusions
  (node_modules/.git/Library/.Trash), 10s walk timeout with partial results.
- read: description swapped to pi-verbatim (doctrine moved to the prompt);
  relative paths now resolve against the learner's home like the rest.
- prompts/shared/05-learner-files.md: one minimal doctrine fragment
  composed into BOTH agents (composeInstructions grew a shared/ dir,
  before the agent's own fragments). teacher/30-jobs.md keeps only the
  pdf-dispatch addendum.
- ToolCallCard: the generic quiet tool-call card the user specced -
  collapsed one-liner (tool name + headline argument), expandable to full
  input/output, errors red, image payloads never render. Registered for
  read/ls/find/grep.
- ui-message.ts: TeacherUITools entries for the four tools (mechanical).
- tests: fs-tools suite (glob semantics, pi formats, exclusions, limits),
  registry/card renders, shared-fragment composition pins, tool-registry
  key updates, read re-anchor.

src/agent/prompts/README.md

@@ -8,6 +8,10 @@ System prompts are composed at agent construction (src/agent/teacher-agent.ts),
 Rules for adding a fragment:
 
 - Name it with a numeric order prefix, inside the right agent directory.
+- `shared/` fragments compose into BOTH agents (before their own, after the base) —
+  cross-agent doctrine only (e.g. `05-learner-files.md`); the "never reference the
+  other agent's tools" rule below still applies, so shared fragments may only cover
+  tools both agents actually hold.
 - One fragment per workstream — your brief tells you which filename you own.
 - Document YOUR agent's tools/behaviors exactly; reference tool input field names verbatim (they must match the zod schemas).
 - Keep it tight: fragments are always in context. No restating the base prompt.

src/agent/prompts/shared/05-learner-files.md

@@ -0,0 +1,14 @@
+## Learner files
+
+The learner's files live on his machine. He references them in messages — by full path,
+by name, or by description ("my calculus notes"). Locating and reading them is your job;
+never ask him to paste file contents into the chat.
+
+- Paths resolve against the learner's home directory: relative paths and omitted search
+  roots mean "somewhere in the home directory".
+- The learner may name a file without saying where it is: find it yourself with `find`
+  (glob by filename) or narrow with `ls` before reading. A distinctive name is enough.
+- `grep` searches file contents across a directory — use it when the file is found but
+  the right passage isn't, or to locate material by phrase.
+- Read what you locate with `read` (text in slices, images as attachments). These tools
+  are read-only: you cannot and should not modify anything on his machine.

src/agent/prompts/teacher/30-jobs.md

@@ -34,14 +34,9 @@ without it (offering to re-dispatch is fine if the learner wants the result).
 
 ## Learner source files
 
-The learner may paste **file paths** into the chat — course PDFs, notes, screenshots, code.
-Reading them is on your own terms; nothing is injected automatically.
-
-- For quick looks at plain text or image files, call `read` directly (it returns the text or
-  shows you the image; large files come back in slices with continuation offsets).
-- For PDFs, dispatch a `pdf` job instead: it runs a background reader (triage, targeted
-  extraction, visual page reading) and returns a **brief with page citations** as a new
-  message — the same fire-and-forget discipline as research above. Give it the path exactly
-  as the learner gave it plus the specific question you need answered.
-- Ask for the path when the learner references a file they haven't given you — never ask them
-  to paste file contents into the chat.
+Locating and reading the learner's files is covered by the shared file doctrine above
+(find/ls/grep/read, home-anchored). One addition is yours alone: for **PDFs**, dispatch a
+`pdf` job instead of `read` — it runs a background reader (triage, targeted extraction,
+visual page reading) and returns a **brief with page citations** as a new message, the
+same fire-and-forget discipline as research above. Give it the path plus the specific
+question you need answered.