Files
skillshare/wiki/architecture.md
T
Willie 819546f124 feat(herdr): answer "what needs me" first and preview every row (#836)
* feat(herdr): answer "what needs me" first and preview every row

The panel listed every resource in one long tab and put the detail of a
row in text under it, so the first screen never said whether anything
needed a sync, and a 400px column filled with wrapped lines.

Overview now leads with one headline, one Sync button and a map from the
source to every target, and lists only what needs attention. Library
holds the full lists. A row carries a name and one short state; clicking
it opens a preview dialog with its document, its targets and its
details, so nothing is crammed into the list. MCP previews show the
names of env, header and token entries, never their values.

Target names come from `status` as well as `diff`, because `diff` leaves
out targets that share another target's folder. A machine with
uncommitted or unpushed work offers Sync both ways, since a plain pull
would refuse there. Warnings and errors now clear after 8 s instead of
staying until closed. Dialogs draw their own card and fade in and out.

The map's lines, the target list and the machine's action live in
model.js with tests; rowSub and the hideDisabled filter had no caller
left and are removed.

* fix(herdr): list only the targets a previewed item can reach

The preview's Targets tab was wrong in two cases.

A skill already on some targets but new to one has the state "missing",
and the preview treated that state as "waits everywhere", so targets
already in sync were marked as needing a sync. Only the targets the
item's drift names wait now.

An agent's preview listed every configured target, including ones that
take no agents, as in sync. The loader now keeps the targets that take
skills and the ones `status` reports for agents apart, and the preview
uses the list for the item's kind.

* feat(herdr): sync from Library's waiting group

The redesign left Sync only on Overview, so someone reading the Library
list had to switch tabs to act on the rows in front of them. The
"NEEDS SYNC" header carries Sync again, for the scopes its rows wait in;
when only a hook notice has native changes, its header carries it.

* fix(herdr): keep Sync in Library's toolbar and stop the panel shrinking past its tabs

Sync on the "NEEDS SYNC" header only existed while something waited, so
with everything in sync Library had no way to sync at all. It now sits
in the toolbar beside the filter, primary while something waits.

The panel could be dragged down to 320px, where the tab row no longer
fits beside the scope switch and the switch is cut off. The column's
minimum is 380px, and the tab row is a little tighter.

* fix(herdr): sync every scope a target still waits in from Library

Library's Sync chose its scopes from the waiting rows alone. A target can
wait with no row left, as after uninstalling a project skill that a
copy-mode target still holds, so with All shown and one global row
waiting, Sync ran in the global scope only and left the project copy in
place. Overview already added the scopes with a waiting target.

Both now take their scopes from one model helper, syncScopes, which
covers waiting rows, waiting targets and the nothing-waiting fallback.

* refactor(herdr): finish the review's open findings on the panel

The first review left confirmed findings listed but unfixed, and the
commits after it were never reviewed. This closes both.

The map now counts a waiting MCP server, plugin or hook on the targets
it waits on, so its lines no longer stay green under a headline that
says something waits. A skill's Targets tab takes its targets from
status when status names them: diff also lists targets that take agents
alone. Library's Sync stays disabled until a scope has been read;
before that it sent an empty scope list and reported a sync that never
ran.

The map's trunk and lanes, the two pill switches, the placeholder block
and its pulse each had two or more copies in main.js and now have one.
The Overview headline, a machine's remote line and its waiting targets
move to model.js with tests. README's layout snippet names the 380px
minimum the layout file already has.
2026-11-10 22:25:13 +08:00

11 KiB

Repository Architecture

Use when deciding which layer should own a change, tracing CLI or Web API data flow, or building an initial mental model of the codebase.

Product Boundaries

skillshare's source of truth is either the global configuration directory (~/.config/skillshare/ by default on macOS/Linux) or project-local .skillshare/ state. The CLI transforms or synchronizes skills, agents, extras, MCP servers, hooks, and plugins into each AI tool's native locations. Never infer runtime behavior from README files or documentation alone; verify the current implementation and embedded configuration.

Repository Map

Path Responsibility
cmd/skillshare/ CLI entry point, flag parsing, mode routing, TUIs, and command orchestration
internal/config/ Global/project configuration, registry, migrations, and target resolution; targets.yaml defines built-in targets
internal/<domain>/ Domain logic such as install, sync, audit, MCP, hooks, plugins, and backup
internal/server/ Dashboard HTTP API; routes are registered in server.go and handlers live in handler_*.go
internal/testutil/ Shared isolated Sandbox and CLI runner for integration tests
tests/integration/ CLI integration tests
ui/ React 19 and Vite dashboard; its API client corresponds to internal/server/
website/ Docusaurus public documentation and marketing pages
ai_docs/tests/ Reproducible CLI E2E runbooks
herdr/ Herdr panel mod; it parses the CLI's --json output (list, diff, check, status, mcp list, plugin list, hooks list, audit), so changing those shapes means updating herdr/skillshare/mods/skillshare/model.js and loader.js; hook entries count separately from filtered diagnostic notices, and unnamed native changes retain pending Sync scope
skills/skillshare/ Built-in skill for skillshare users, not internal development instructions
schemas/ Public YAML/JSON schemas; inspect these when configuration shapes change
scripts/, Makefile, mise.toml Build, test, devcontainer, and verification entry points

Request Flow

A typical CLI request follows this path:

  1. The commands map in cmd/skillshare/main.go dispatches the command.
  2. cmd/skillshare/<command>.go parses flags and selects global or project mode.
  3. cmd/skillshare/<command>_*.go composes domain operations, prompts, and output.
  4. internal/<domain>/ performs filesystem, Git, configuration, or audit logic.
  5. Mutating operations write to operations.log through internal/oplog; security scans use the audit log.

A typical dashboard request follows this path:

  1. ui/src/api/client.ts sends the request.
  2. A route registered in internal/server/server.go enters handler_<domain>.go.
  3. The handler uses the same internal/ domain package as the CLI. Do not duplicate core behavior in the frontend or handler.
  4. Project/global differences use the server mode and existing helpers rather than a separate data model.

Shared Memory Notes

internal/memory owns note discovery, bounded UTF-8 reads, content-version writes/deletes/moves, backups, index inspection/link append, and scope/hash-marked guidance. CLI extras memory and dashboard handlers share its store and existing extra source resolution. Initialization preserves notes and creates missing INDEX.md/LEARNED.md; the source-only extra requires no targets. Dashboard initialization requires both readable starters and the configured extra; note creation repairs missing starters before using the refreshed index. Unsupported notes remain listed and do not block valid notes. Explicit dashboard index actions append at EOF with version checks/backups; failed linking preserves a created note. Broken links are reported without rewriting user-owned index sections. Prepared writes and deletions recheck the version after backup immediately before replacement/removal; new notes use exclusive creation to reject concurrent creates.

Note includes the file's UTC modified_at and a starter flag for content that exactly matches an untouched built-in starter. The dashboard lists up to four recently modified readable non-starter notes and links to the existing Memory browser; its summary uses the unfiltered notes even while searching. The dashboard uses /api/extras/memory/recent: it counts entries from metadata and reads at most the two starters and four recent candidates. The full list and content APIs remain available to the Memory browser. Preview expansion is a browser preference shared across notes; collapsed previews allow 360 px.

handler_memory_guidance.go only resolves existing target read chains and instruction assignments into memory.GuidanceInput (including which file receives a new block) and converts results to JSON; internal/memory/guidance_plan.go owns status, plan, and apply (GuidanceStatus, PlanGuidance, ApplyGuidance), tested against a temp directory. Plan returns per-file before/after content, skips, reader/size warnings, and a token; apply recomputes it before backed-up writes, and a callback lets the server sync shared copies after each written file. Each file is checked against its reviewed content and existence before writing, including after backup. A later conflict preserves that file and reports memory_guidance_stale in the partial result alongside applied paths. New guidance files use exclusive creation; a competing creator also produces memory_guidance_stale without overwriting its file. It preserves other content, assignments, and connection modes. Each block records its update mode (passive, the default and unmarked, or active) in its begin marker, and status is checked against that mode's text. Plan and apply take a mode per target; a target left out keeps its block's mode. Targets reading one file share its block, so different modes for one file are rejected. A target whose live chain holds blocks of both modes is broken/mixed_modes; switching a target that reads blocks in several files is skipped as multiple_blocks, since rewriting one file would leave the others. Intact outdated blocks can be updated after review; modified/malformed blocks are protected. Non-UTF-8 instruction files are reported as broken/unsupported and skipped without rewriting their bytes; instruction files have no size cap, and known character limits are review warnings. Guidance paths inside a project are relative to the project root; external sources remain absolute. GET reports file-based configuration state, never agent reads. Fresh-session read events provide manual verification only.

Memory tools copy a three-step cross-session trial (save, read, cleanup), a session retrospective, and a Dreaming prompt for the current source. Dashboard and Memory share the same dialog; the recent endpoint includes the resolved source root without extra note reads. Retrospectives review available session evidence for durable lessons and separate memory proposals from project-check advice. Dreaming can synthesize saved lessons with multi-session provenance; no private history scan or transcript archive is required. Three inline modes show concise steps with full scoped prompts collapsed by default. Tools stay disabled until the overview confirms global/project scope and, for projects, the project root. Both review prompts require versioned CLI writes and stop on a source mismatch, unavailable CLI, or conflict. The built-in skill routes to references/memory-review.md for host-owned review and approved versioned writes. Reading guidance suggests review opportunities once, without starting one. The read prompt omits the test value. Both guidance modes request decision/lesson provenance and successful-write reports naming the content, scope and file path. Existing blocks update only through the reviewed guidance flow. Prompts do not execute agents or provide read telemetry.

The Memory tab uses the shared tree/Markdown editor. Conflicts retain drafts, display latest saved content, and require confirmation before a version-checked, backed-up replacement. History/restore links filter Backup Files by absolute note path, and a requested path without backups shows an empty state. Windows history links compare normalized separators while backup API calls retain the native path; POSIX names retain literal backslashes. Project backup scope includes its configured memory source even outside the repository; without a configured memory extra, external backup access remains denied. Backup handlers hold the configuration lock from scope validation through reads or restore writes, so removing a memory extra cannot invalidate an active check. Initialization failures, including partial file creation, are logged. Dashboard move/rename preserves note content and permissions, creates missing parent folders, rejects stale versions and existing destinations, and backs up the source path. Links and path-keyed history remain at their original paths; index inspection reports broken links after a move. Native automatic memory, telemetry, and Obsidian integration are outside this boundary.

Sources of Truth

  • Command flags and behavior: cmd/skillshare/*.go.
  • Target names, aliases, and default paths: internal/config/targets.yaml.
  • Built-in audit rules: internal/audit/rules.yaml and related table-driven analyzers.
  • Public configuration contracts: schemas/*.json and configuration parsing/validation code.
  • Dashboard design values: ui/src/components.css and ui/src/index.css.
  • Website design values: website/src/css/custom.css and page CSS modules.
  • Build and test commands: Makefile, mise.toml, and CI workflows.

Trace Checklist

Before changing code:

  1. Search for the existing symbol, flag, or route and find its definition, callers, and tests.
  2. Determine whether both global and project mode are affected.
  3. If the CLI and Web API expose the same behavior, verify that they share domain logic.
  4. For state changes, inspect backup, rollback, oplog, dry-run, and audit implications.
  5. Load documentation for public contract changes, cli-development for implementation, and testing before execution.

Project registration overlay

Config loads shared projects then a versioned machine-local overlay. Local entries replace whole normalized roots; exclusions hide shared entries only here. Effective Projects expands into targets for sync consumers. General Save/PrepareSave projects back to shared declarations; local registrations never leak into shared config. internal/projects.Service edits both layers through config.PrepareProjectLayers: a new project goes to the layer projects_storage or the caller picks (shared by default), and edits and removals stay in the owning layer. A change to both layers (share, removal of an override with Shared) writes config.yaml before the local registry, so an interrupted write keeps the project. Dashboard target conversion remains a shared single-file write and refuses hidden roots. Raw editor decoding validates the submitted shared document plus overlay.

ProjectStateDir isolates Windows registrations from the default config Git root using LocalAppData. Registry and locks share ProjectConfigIdentity, keyed by the resolved config destination, including the legacy Windows migration alias. Prepared local writes check shared/local bytes and config-link destination before detach and rename. Shared-writer concurrency outside this service remains separate.