# thoughtframe-core — agent notes

This repo runs a live ThoughtFrame engine inside Eclipse, driven through the `tf` client
(a thin HTTP client; it finds the port in `~/.thoughtframe/instances/*.json`).

**Prefer `tf` over the shell** for work in this workspace — it's indexed, scoped to the
real workspace, and goes through Eclipse, so the IDE stays the source of truth. Prefer it
over shell `grep`/`find`/`ls`, and `tf write`/`tf replaceSelection` over direct FS edits.
Run `tf help` for the live list. Verb pages are grouped in subfolders (search/ read/
edit/ run/ debug/ agent/ engine/); the `tf` client maps names to folders, so you still
type `tf VERB`. The verbs:

Search (Eclipse JDT index)
  tf find name=…                     type declarations (e.g. *Manager)
  tf references class=… [method=|field=]
  tf implementors class=… [method=]  subtypes / overrides
  tf hierarchy class=…               supertypes + subtypes
  tf type-info class=…               fields, methods, supertypes
  tf source class=…                  the type's source

Read
  tf status                          dashboard: editor, problems, launches, tests
  tf projects | tf project name=… | tf projectState name=&op=open|close
  tf editors | tf selection | tf stat path=… | tf properties path=… | tf classpath project=…
  tf markers [severity=] | tf tasks | tf bookmarks op=list | tf console [name=] [lines=]
  tf tests op=runs | tf problems [path=…]
  tf glob pattern=… | tf grep query=… [path=] | tf peek path=… [startLine= count=]
  tf git project=… op=status|log|branch|diff [path=]

Edit (through Eclipse — creates parents, auto-reveals)
  tf open path=… [line=] | tf close | tf save [all=true]
  tf write path=… text=… | tf replaceSelection path=… before=|from=+to= text=…
  tf delete | tf mkdir | tf moveFile path=&to= | tf copy path=&to=
  tf move class=&target= | tf rename class=&newName=      (Eclipse LTK refactoring)
  tf format | tf formatAll path=… | tf organizeImports | tf highlight … | tf refresh

Build / run / debug
  tf build | tf clean [name=] | tf run | tf runTests project=…
  tf launch op=configs|running|run|stop name=… | tf launchConfig op=delete name=…
  tf debug op=launch name=…          launch a config in debug mode
  tf debug op=targets|threads|variables&thread=&frame=
  tf debug op=resume|suspend|stepOver|stepInto|stepReturn     (step over = stepOver)
  tf breakpoints op=list|set|clear path=&line=    (set takes path + line; the type is derived)
  tf runCommand command=…            any workbench command id

Extend / misc
  tf reloadframeplugins | tf clearCache | tf errors [lines=]
  tf websearch query=… (needs a key) | tf webfetch url=… [format=text] | tf scratch
  tf thought op=add|search|delete|taxonomy …  (agent memory via the "thought" searcher)

Engine
  tf engine status | frame framepath=… | tick framepath=… | until … | runframe …
  tf engine frames op=neighbours|connect|near|here …   (frame graph; topics are frames)

Notes
- After editing engine Java the running engine is stale: check `tf errors` (Hot Code
  Replace failures land there), then restart the target (`tf launch op=stop` +
  `tf debug op=launch`). Better: draft it as a webapp Groovy page — that's live, no restart.
- For throwaway scripts, prefer a scratch Groovy page run in the engine (`tf scratch`)
  over shell one-liners: it runs in-process with `context` and `bench` in scope.
- Everything searchable goes through ONE interface — `Searcher` (`bench.getSearcher("type")`
  + `QueryBuilder`) — backed by the embedded OpenSearch node: frames, thoughts, git repos,
  notes, framememory/RAG. It is already wired; do NOT reverse-engineer the search layer.
  Query idiom, semantic `deepsearch`, and "add a type by copying
  `WEB-INF/base/tf-eclipse/system/data/fields/<type>.xml`" are in `tf help`. Copy the
  nearest example (`agent/notes.*` is the minimal one); deep-reading the framework is
  what makes agent context explode.
- If a capability looks missing or unwired and you're about to deep-read the framework to
  find out, STOP and ASK the user first. Don't spelunk; only the user knows what's already
  there, and guessing is what burns the context.
- Keep state in the graph, not just the conversation: recall with `tf thought op=search …`
  / `tf engine frames op=near framepath=topic/…` as you work, and write decisions to
  `topic/<slug>` after (`tags`/`status`; `status=parked` for measure-later items). Check it
  while you work, not only at the end.