fix: address open review findings across skills, vector, and docs

- Move the generated-by header inside the SKILL.md frontmatter fence so
  frontmatter-based skill discovery keeps working; files now begin with
  "---" and Classify reads the header from line two.
- Tighten the embedding 4xx skip classifier: a size word must pair with
  an input word and "content" with "policy", so auth ("invalid token")
  and media-type ("unsupported content type") failures abort the build
  instead of skip-stamping the corpus.
- Double-wrap query-encode failures so context.Canceled/DeadlineExceeded
  stay matchable through db.ErrSemanticTransient.
- Set USERPROFILE alongside HOME in skills CLI tests for Windows runs.
- Spell out --since units (m = months, not minutes) in flag help, the
  session API tables, and the skill template.
- Correct internals docs: skip-and-stamp taxonomy now matches the
  400/413/422 allowlist, and the mirror-corpus note no longer claims
  parity with unfiltered FTS.
- Regenerate the frontend API client (search intent header, embeddings
  routes, and earlier drift) and update two activity test fixtures for
  the now-required projects field.

Author: wesm

cmd/agentsview/embed_scheduler.go

@@ -301,7 +301,10 @@ func translateSearchError(err error) error {
 	case errors.Is(err, vector.ErrNoActiveGeneration):
 		return db.ErrSemanticUnavailable
 	case errors.As(err, &queryEncErr):
-		return fmt.Errorf("%w: %v", db.ErrSemanticTransient, queryEncErr.Err)
+		// Double-wrap so callers can still match the underlying cause —
+		// notably context.Canceled/DeadlineExceeded from a dead client —
+		// alongside the transient sentinel.
+		return fmt.Errorf("%w: %w", db.ErrSemanticTransient, queryEncErr.Err)
 	default:
 		return err
 	}

cmd/agentsview/embed_scheduler_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"errors"
+	"fmt"
 	"mime"
 	"net"
 	"net/http"
@@ -449,6 +450,15 @@ func TestTranslateSearchErrorMapsVectorErrorsToSemanticUnavailable(t *testing.T)
 			"a query-time endpoint failure must not read as semantic search being disabled")
 		assert.Contains(t, got.Error(), "connection refused")
 	})
+	t.Run("query encode failure preserves the underlying cause chain", func(t *testing.T) {
+		queryErr := &vector.QueryEncodeError{
+			Err: fmt.Errorf("encoding query: %w", context.Canceled),
+		}
+		got := translateSearchError(queryErr)
+		assert.ErrorIs(t, got, db.ErrSemanticTransient)
+		assert.ErrorIs(t, got, context.Canceled,
+			"context errors must stay matchable so cancellation handling still fires")
+	})
 }
 
 // --- integration: real serve/server construction path ---

cmd/agentsview/session_list.go

@@ -143,7 +143,7 @@ func newSessionListCommand() *cobra.Command {
 	flags.StringVar(&activeSince, "active-since", "",
 		"Filter sessions active since RFC3339 timestamp")
 	flags.StringVar(&since, "since", "",
-		"Only sessions active since a relative duration (3m, 14d, 12h, 1y) or YYYY-MM-DD")
+		"Only sessions active since a relative duration (12h, 14d, 2w, 3m = 3 months, 1y) or YYYY-MM-DD")
 	flags.IntVar(&minMessages, "min-messages", 0,
 		"Minimum total message count")
 	flags.IntVar(&maxMessages, "max-messages", 0,

cmd/agentsview/session_search.go

@@ -108,7 +108,7 @@ func newSessionSearchCommand() *cobra.Command {
 	flags.StringVar(&dateTo, "date-to", "", "Sessions on or before YYYY-MM-DD")
 	flags.StringVar(&activeSince, "active-since", "", "Active since RFC3339 timestamp")
 	flags.StringVar(&since, "since", "",
-		"Only sessions active since a relative duration (3m, 14d, 12h, 1y) or YYYY-MM-DD")
+		"Only sessions active since a relative duration (12h, 14d, 2w, 3m = 3 months, 1y) or YYYY-MM-DD")
 	flags.BoolVar(&includeChildren, "include-children", false, "Include subagent sessions")
 	flags.BoolVar(&includeAutomated, "include-automated", false, "Include automated sessions")
 	flags.BoolVar(&includeOneShot, "include-one-shot", false, "Include one-shot sessions")

cmd/agentsview/skills_test.go

@@ -56,22 +56,29 @@ func writeSkillFile(t *testing.T, path, content string) {
 	require.NoError(t, os.WriteFile(path, []byte(content), 0o644))
 }
 
+// setTestHome points the process home at dir for both Unix (HOME) and
+// Windows (USERPROFILE), since os.UserHomeDir reads a different variable
+// per platform.
+func setTestHome(t *testing.T, dir string) {
+	t.Helper()
+	t.Setenv("HOME", dir)
+	t.Setenv("USERPROFILE", dir)
+}
+
 // staleClaudeContent returns a well-formed generated-by file whose recorded
 // hash matches an older body, so Classify reports StateStale.
 func staleClaudeContent() string {
-	oldBody := "an earlier revision of the skill body, no longer current\n"
+	oldBody := "---\nname: agentsview-finding-history\n---\n" +
+		"an earlier revision of the skill body, no longer current\n"
 	header := fmt.Sprintf(skillHeaderFormat, "0.0.1", sha256Hex(oldBody))
-	return header + "\n" + oldBody
+	return "---\n" + header + "\n" + strings.TrimPrefix(oldBody, "---\n")
 }
 
 // modifiedClaudeContent returns a fresh render whose body was hand-edited
 // after the header hash was recorded, so Classify reports StateModified.
 func modifiedClaudeContent(t *testing.T) string {
 	t.Helper()
-	fresh := freshClaudeSkill(t)
-	headerLine, body, ok := strings.Cut(fresh.Content, "\n")
-	require.True(t, ok)
-	return headerLine + "\n" + body + "\nan uninvited local edit\n"
+	return freshClaudeSkill(t).Content + "\nan uninvited local edit\n"
 }
 
 const foreignClaudeContent = "# Just a hand-written file\n\nNo generated-by header here.\n"
@@ -126,7 +133,7 @@ func TestSkillsInstall_StatesAndForce(t *testing.T) {
 		for _, force := range []bool{false, true} {
 			t.Run(fmt.Sprintf("%s/force=%v", tt.name, force), func(t *testing.T) {
 				home := t.TempDir()
-				t.Setenv("HOME", home)
+				setTestHome(t, home)
 				path := claudeSkillPath(home)
 
 				var seedContent string
@@ -175,7 +182,7 @@ func readFileString(t *testing.T, path string) string {
 
 func TestSkillsInstall_DefaultHarnessesInstallBoth(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 
 	out, err := executeCommand(newRootCommand(), "skills", "install")
 	require.NoError(t, err, "output: %s", out)
@@ -188,7 +195,7 @@ func TestSkillsInstall_DefaultHarnessesInstallBoth(t *testing.T) {
 
 func TestSkillsInstall_UnknownHarnessErrors(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 
 	_, err := executeCommand(newRootCommand(), "skills", "install", "--harness", "bogus")
 	require.Error(t, err)
@@ -197,7 +204,7 @@ func TestSkillsInstall_UnknownHarnessErrors(t *testing.T) {
 
 func TestSkillsInstall_RefusalStillInstallsOtherTargets(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 	writeSkillFile(t, claudeSkillPath(home), foreignClaudeContent)
 
 	out, err := executeCommand(newRootCommand(), "skills", "install")
@@ -212,7 +219,7 @@ func TestSkillsInstall_RefusalStillInstallsOtherTargets(t *testing.T) {
 
 func TestSkillsInstall_FilePermissions(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 
 	_, err := executeCommand(newRootCommand(), "skills", "install", "--harness", "claude")
 	require.NoError(t, err)
@@ -268,7 +275,7 @@ func TestSkillsList_ReportsEachState(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			home := t.TempDir()
-			t.Setenv("HOME", home)
+			setTestHome(t, home)
 			path := claudeSkillPath(home)
 			if tt.seed != nil {
 				tt.seed(t, path)
@@ -296,7 +303,7 @@ func TestSkillsList_ReportsEachState(t *testing.T) {
 
 func TestSkillsList_HumanTableHasHeaderAndColumns(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 
 	out, err := executeCommand(newRootCommand(), "skills", "list")
 	require.NoError(t, err, "output: %s", out)
@@ -327,7 +334,7 @@ func initTestGitRepo(t *testing.T) string {
 
 func TestSkillsInstall_ProjectFlagUsesGitRoot(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 
 	repo := initTestGitRepo(t)
 	nested := filepath.Join(repo, "a", "b")
@@ -346,7 +353,7 @@ func TestSkillsInstall_ProjectFlagUsesGitRoot(t *testing.T) {
 
 func TestSkillsList_ProjectFlagReportsProjectLevel(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 
 	repo := initTestGitRepo(t)
 	t.Chdir(repo)
@@ -365,7 +372,7 @@ func TestSkillsList_ProjectFlagReportsProjectLevel(t *testing.T) {
 
 func TestSkillsInstall_ProjectFlagOutsideRepoFallsBackToCWD(t *testing.T) {
 	home := t.TempDir()
-	t.Setenv("HOME", home)
+	setTestHome(t, home)
 
 	outsideRepo := t.TempDir()
 	resolvedOutside, err := filepath.EvalSymlinks(outsideRepo)

docs/semantic-search-internals.md

@@ -29,10 +29,11 @@ special-casing during the swap instead of a plain re-scan afterward.
 ### The `vector_messages` mirror table
 
 One row per embeddable message (`role IN ('user','assistant')`, non-system,
-non-system-prefixed — the same universe FTS uses before `--exclude-system`).
-Columns: `doc_key` (primary key), `session_id`, `source_uuid`, `ordinal`,
-`content` (copied text), `content_hash` (sha256 of content, kit's revision
-column), `embed_gen`.
+non-system-prefixed — the corpus semantic and hybrid search operate on; the
+hybrid FTS leg applies the same predicate, while plain FTS content search is
+broader unless filters narrow it). Columns: `doc_key` (primary key),
+`session_id`, `source_uuid`, `ordinal`, `content` (copied text), `content_hash`
+(sha256 of content, kit's revision column), `embed_gen`.
 
 ### `doc_key` scheme
 
@@ -97,14 +98,18 @@ re-embedding.
 
 Fill embeds every pending document (content changed, or never embedded, for the
 active generation). A document whose encode call fails with a permanent error —
-any 4xx except 429, e.g. token-window overflow or a content-policy rejection —
-is not retried in that fill or the next one: it's stamped for the generation
-with no vectors at its current `content_hash`, which marks it non-pending. It's
-logged (doc key plus the underlying error) and counted in the build summary's
-skipped count, but there is no separate poison list or periodic retry — the only
-way it embeds again is if the message's content itself changes later (a new
-`content_hash`, so a new pending row). All other failures (5xx, network errors,
-timeouts, 429) abort the fill and are retried on the next scheduled build.
+a 400, 413, or 422 whose error body describes the input itself, e.g. a
+token/context-length overflow or a content-policy rejection — is not retried in
+that fill or the next one: it's stamped for the generation with no vectors at
+its current `content_hash`, which marks it non-pending. It's logged (doc key
+plus the underlying error) and counted in the build summary's skipped count, but
+there is no separate poison list or periodic retry — the only way it embeds
+again is if the message's content itself changes later (a new `content_hash`, so
+a new pending row). Every other failure — 5xx, network errors, timeouts, 429,
+and any 4xx that looks like an auth, route, model, or media-type problem rather
+than a rejection of this document — aborts the fill and is retried on the next
+scheduled build, so a config mistake can't silently stamp the whole corpus as
+embedded-with-no-vectors.
 
 ### Scope (`include_automated`)
 
@@ -178,14 +183,16 @@ single embedded template, `internal/skills/templates/finding-history.md.tmpl`
 via `go:embed` — the same pattern `internal/web` uses for the frontend — with no
 per-harness copies checked in. `Render` fills in a harness-specific delegation
 phrase (whether the harness can dispatch a search subagent or must run the
-bounded probes itself) and prepends a `generated-by` header carrying the CLI
-version and a sha256 hash of the rendered body. Staleness and tamper detection
-are hash-authoritative, not version-authoritative: `Classify` compares a file's
-recorded hash against its own body hash to detect modification, and against a
-fresh render's hash to detect staleness, and never consults the version string,
-because dev builds all report version `"dev"` and would otherwise be
-indistinguishable from one another. There is deliberately no Claude Code
-plugin/marketplace packaging: that would tie distribution to one harness's
+bounded probes itself) and inserts a `generated-by` header — carrying the CLI
+version and a sha256 hash of the pure template render — as a YAML comment on
+line two, just inside the frontmatter fence, so the file still begins with `---`
+and frontmatter-based skill discovery keeps working. Staleness and tamper
+detection are hash-authoritative, not version-authoritative: `Classify` compares
+a file's recorded hash against its own body hash to detect modification, and
+against a fresh render's hash to detect staleness, and never consults the
+version string, because dev builds all report version `"dev"` and would
+otherwise be indistinguishable from one another. There is deliberately no Claude
+Code plugin/marketplace packaging: that would tie distribution to one harness's
 install mechanism, whereas the goal is a single `SKILL.md` artifact that any
 `.agents/skills`-reading harness can consume the same way, installed directly by
 the `agentsview` binary rather than a separate package manager.

docs/semantic-search.md

@@ -315,14 +315,15 @@ agentsview skills list                       # show install state per harness
 the working directory itself outside a repo), writing to `.claude/skills/...`
 and `.agents/skills/...` instead.
 
-Every rendered file starts with a `generated-by` header carrying a content hash.
-`install` overwrites a file whose hash still matches its header (unmodified
-since the last install) but refuses a file that was hand-edited or was never
-generated by `agentsview`, printing which paths it refused and exiting non-zero;
-pass `--force` to overwrite anyway. Re-run `agentsview skills install` after
-upgrading `agentsview` to pick up skill content changes — the header records the
-CLI version for humans, but the content hash, not the version, decides whether a
-reinstall is a no-op.
+Every rendered file carries a `generated-by` header with a content hash, written
+as a YAML comment just inside the frontmatter fence so the file still starts
+with `---` and harnesses keep discovering it. `install` overwrites a file whose
+hash still matches its header (unmodified since the last install) but refuses a
+file that was hand-edited or was never generated by `agentsview`, printing which
+paths it refused and exiting non-zero; pass `--force` to overwrite anyway.
+Re-run `agentsview skills install` after upgrading `agentsview` to pick up skill
+content changes — the header records the CLI version for humans, but the content
+hash, not the version, decides whether a reinstall is a no-op.
 
 `agentsview skills list [--project] [--format json]` reports each harness's
 install state — `missing`, `current`, `stale` (unmodified but older than the

docs/session-api.md

@@ -226,7 +226,7 @@ One-shot and automated sessions are excluded by default. Use the
 | `--date-from`         | `date_from`         | `YYYY-MM-DD`                      |
 | `--date-to`           | `date_to`           | `YYYY-MM-DD`                      |
 | `--active-since`      | `active_since`      | RFC3339 timestamp                 |
-| `--since`             | `active_since`      | Relative (`3m`, `14d`, `12h`, `1y`) or `YYYY-MM-DD`; resolved against now and mutually exclusive with `--active-since` |
+| `--since`             | `active_since`      | Relative — `Nh` hours, `Nd` days, `Nw` weeks, `Nm` calendar months (not minutes), `Ny` years — or `YYYY-MM-DD`; resolved against now and mutually exclusive with `--active-since` |
 | `--resume`            | `active_since`      | CLI shortcut for sessions active in the last 15 minutes |
 | `--active`            | `active_since`      | Alias for `--resume`              |
 | `--min-messages`      | `min_messages`      | int                               |
@@ -568,7 +568,7 @@ default; opt back in with `--include-one-shot`,
 | `--date-from`         | `date_from`         | `YYYY-MM-DD`                                           |
 | `--date-to`           | `date_to`           | `YYYY-MM-DD`                                           |
 | `--active-since`      | `active_since`      | RFC3339 timestamp                                      |
-| `--since`             | `active_since`      | Relative (`3m`, `14d`, `12h`, `1y`) or `YYYY-MM-DD`; resolved against now and mutually exclusive with `--active-since` |
+| `--since`             | `active_since`      | Relative — `Nh` hours, `Nd` days, `Nw` weeks, `Nm` calendar months (not minutes), `Ny` years — or `YYYY-MM-DD`; resolved against now and mutually exclusive with `--active-since` |
 | `--include-children`  | `include_children`  | bool                                                   |
 | `--include-automated` | `include_automated` | bool                                                   |
 | `--include-one-shot`  | `include_one_shot`  | bool                                                   |