T-FSMC-author-a-plain-reference-note-in-app

State: closed/done · Impact: high · Complexity: medium

Goal

Every in-app creation path produces a kind-typed component — a skill, command, agent, plugin, or marketplace. Nothing creates a plain, untyped note that a skill body can wikilink as a reference. An author has to leave the app to make one, which most authors will not think to do.

A role note — a shared “You are a…” preamble an agent or skill embeds, see solutions/agent-pants/docs/vault/glossary/role.md — is the first concrete case for this gap: it is exactly a plain reference note, and today an author has to leave the app to create one.

Today

Location	Role today
solutions/determined/experiences/agent-pants/app/components/ApNewComponentWizard.vue:132-186	kindCards builds the What step’s options from kind_dirs (skill, command, agent) plus CONTAINER_KINDS (plugin, marketplace); nothing offers an untyped note
solutions/determined/experiences/agent-pants/app/utils/wizardSeed.ts:12-20	WizardSeedKind is a closed union of 'skill' | 'command' | 'agent' | 'plugin' | 'marketplace'; no value for a reference note
solutions/determined/experiences/agent-pants/docs/authoring.md:71-84	”Referencing a plain note” tells the reader to create one “the way you create any other note today, in Obsidian or any editor” — the docs hint added after the survey, not an in-app flow
solutions/determined/crates/determined-core/src/wire/mod.rs:2379-2387	AgentSkillNotePlacement.kind is mandatory and parses as an EntityKind; there is no placement that means “no kind, just a folder”
solutions/determined/crates/determined-agent-skills/src/lib.rs:233-270 (new_note_dir)	Derives a note’s folder strictly from a kind folder (KIND_DIRS) or a container’s own folder; refuses any kind it cannot parse
solutions/determined/crates/determined-agent-skills/src/lib.rs:2806 (create_note)	Always creates the entry note of a new component at a derived path; nothing writes an arbitrary-named peer file beside an existing skill

Proposed

A “New reference note” entry, offered beside the kind cards in the wizard (or from a skill page’s plus menu), writes a plain note — no ap-kind, no modelled fields — under a skill’s own folder or a vault-level references/ folder. A skill authored in the wizard can wikilink the result, and publishing that skill carries the reference alongside it, the same way a reference authored outside the app already travels today.

Approach

1. Decide the placement: a sibling file inside an already-bundled skill’s own folder (reusing the peer-resource carrying agent-adapt-core already does for linked/embedded files), or a new vault-level references/ folder needing its own KIND_DIRS entry. Either needs a backend change — AgentSkillNotePlacement/new_note_dir has no “place this with no kind” option today.
2. Extend the backend: either a new operation that writes an arbitrary-named, frontmatter-free file into an existing bundle folder, or a no-op EntityKind variant plus a KIND_DIRS entry for references, whichever the decision in step 1 picks.
3. Add 'reference' to WizardSeedKind in wizardSeed.ts, and a card for it in ApNewComponentWizard.vue’s kindCards.
4. Give the reference flow its own step list — What → Where → Body → Review — skipping Details entirely, since a plain note has no fields to ask about.
5. Offer the entry from a skill page’s plus menu as well as the wizard’s own What step, seeded to that skill’s placement.
6. Update authoring.md’s “Referencing a plain note” section to describe the in-app path, keeping the external-editor path as still valid.

Files to touch

Location	Kind	Change
solutions/determined/crates/determined-core/src/wire/mod.rs	modify	New placement/kind surface for a reference note, per the decision in step 1
solutions/determined/crates/determined-agent-skills/src/lib.rs	modify	new_note_dir and create_note (or a new sibling operation) handle the reference case
solutions/determined/experiences/agent-pants/app/utils/wizardSeed.ts	modify	Add 'reference' to WizardSeedKind
solutions/determined/experiences/agent-pants/app/components/ApNewComponentWizard.vue	modify	A reference card, its own step list, and a Create call with no modelled fields
solutions/determined/experiences/agent-pants/app/components/ApComponentTree.vue	modify	Skill-page plus menu offers “New reference note”
solutions/determined/experiences/agent-pants/docs/authoring.md	modify	”Referencing a plain note” describes the in-app path

Acceptance criteria

• AC-1: A “New reference note” entry is offered from the wizard’s What step or a skill page’s plus menu, and produces a plain note with no ap-kind and no modelled fields.
• AC-2: A skill authored in the wizard can wikilink the new reference note, and publishing that skill carries the reference alongside it.
• AC-3: authoring.md’s “Referencing a plain note” section describes the in-app path and no longer says creating one requires leaving the app.
• AC-4: A regression test covers creating a reference note and a publish that carries it.

Out of scope

• Giving a reference note any modelled frontmatter fields. It stays untyped by design — that is what makes it a reference rather than a component.

Dependencies

• none

Discovery context

Found by the agent-pants bug survey, N-5LD4-bug-sweep-2026-09-12-agent-pants (rows AP-37, AP-67).

---

← Back to Tasks