@mepuka/skygent 0.2.0 → 0.3.0

package/src/cli/feed.ts

@@ -1,14 +1,17 @@
 import { Args, Command, Options } from "@effect/cli";
-import { Effect, Option, Stream } from "effect";
+import { Effect, Stream } from "effect";
 import { renderTableLegacy } from "./doc/table.js";
+import { renderFeedTable } from "./doc/table-renderers.js";
 import { BskyClient } from "../services/bsky-client.js";
-import type { FeedGeneratorView } from "../domain/bsky.js";
 import { AppConfigService } from "../services/app-config.js";
-import { decodeActor, parseLimit } from "./shared-options.js";
+import type { FeedGeneratorView } from "../domain/bsky.js";
+import { decodeActor } from "./shared-options.js";
 import { CliInputError } from "./errors.js";
 import { withExamples } from "./help.js";
 import { writeJson, writeJsonStream, writeText } from "./output.js";
-import { jsonNdjsonTableFormats, resolveOutputFormat } from "./output-format.js";
+import { jsonNdjsonTableFormats } from "./output-format.js";
+import { emitWithFormat } from "./output-render.js";
+import { cursorOption as baseCursorOption, limitOption as baseLimitOption, parsePagination } from "./pagination.js";
 
 const feedUriArg = Args.text({ name: "uri" }).pipe(
   Args.withDescription("Bluesky feed URI (at://...)")
@@ -23,14 +26,12 @@ const actorArg = Args.text({ name: "actor" }).pipe(
   Args.withDescription("Bluesky handle or DID")
 );
 
-const limitOption = Options.integer("limit").pipe(
-  Options.withDescription("Maximum number of results"),
-  Options.optional
+const limitOption = baseLimitOption.pipe(
+  Options.withDescription("Maximum number of results")
 );
 
-const cursorOption = Options.text("cursor").pipe(
-  Options.withDescription("Pagination cursor"),
-  Options.optional
+const cursorOption = baseCursorOption.pipe(
+  Options.withDescription("Pagination cursor")
 );
 
 const formatOption = Options.choice("format", jsonNdjsonTableFormats).pipe(
@@ -38,19 +39,6 @@ const formatOption = Options.choice("format", jsonNdjsonTableFormats).pipe(
   Options.optional
 );
 
-const renderFeedTable = (
-  feeds: ReadonlyArray<FeedGeneratorView>,
-  cursor: string | undefined
-) => {
-  const rows = feeds.map((feed) => [
-    feed.displayName,
-    feed.creator.handle,
-    feed.uri,
-    typeof feed.likeCount === "number" ? String(feed.likeCount) : ""
-  ]);
-  const table = renderTableLegacy(["NAME", "CREATOR", "URI", "LIKES"], rows);
-  return cursor ? `${table}\n\nCursor: ${cursor}` : table;
-};
 
 const renderFeedInfoTable = (
   view: FeedGeneratorView,
@@ -70,17 +58,17 @@ const showCommand = Command.make(
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
       const result = yield* client.getFeedGenerator(uri);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJson(result),
+          table: writeText(renderFeedInfoTable(result.view, result.isOnline, result.isValid))
+        }
       );
-      if (outputFormat === "table") {
-        yield* writeText(renderFeedInfoTable(result.view, result.isOnline, result.isValid));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -104,21 +92,17 @@ const batchCommand = Command.make(
         });
       }
       const result = yield* client.getFeedGenerators(uris);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.feeds)),
+          table: writeText(renderFeedTable(result.feeds, undefined))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.feeds));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderFeedTable(result.feeds, undefined));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -135,27 +119,23 @@ const byActorCommand = Command.make(
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const resolvedActor = yield* decodeActor(actor);
       const result = yield* client.getActorFeeds(resolvedActor, {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       });
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.feeds)),
+          table: writeText(renderFeedTable(result.feeds, result.cursor))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.feeds));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderFeedTable(result.feeds, result.cursor));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(

package/src/cli/filter-dsl.ts

@@ -1,14 +1,15 @@
-import { Context, Duration, Effect, Schema } from "effect";
+import { Clock, Context, Duration, Effect, Schema } from "effect";
 import { formatSchemaError } from "./shared.js";
 import type { FilterEngagement, FilterExpr } from "../domain/filter.js";
 import { all, and, none, not, or } from "../domain/filter.js";
 import type { FilterErrorPolicy } from "../domain/policies.js";
 import { ExcludeOnError, IncludeOnError, RetryOnError } from "../domain/policies.js";
-import { Handle, Hashtag, StoreName } from "../domain/primitives.js";
+import { Handle, Hashtag, StoreName, Timestamp } from "../domain/primitives.js";
 import { FilterLibrary } from "../services/filter-library.js";
 import { FilterLibraryError, FilterNotFound } from "../domain/errors.js";
 import { CliInputError } from "./errors.js";
 import { parseRange } from "./range.js";
+import { parseDurationInput, parseTimeInput } from "./time.js";
 
 type Token =
   | { readonly _tag: "Word"; readonly value: string; readonly position: number }
@@ -212,7 +213,8 @@ const normalizeOptionKey = (key: string) =>
 const normalizeFilterKey = (key: string) => key.trim().toLowerCase();
 
 const unsupportedFilterKeys = new Map<string, string>([
-  ["label", "Label filters are not supported yet."]
+  ["label", "Label filters are not supported yet."],
+  ["labels", "Label filters are not supported yet."]
 ]);
 
 const filterKeyHints = new Map<string, string>([
@@ -235,7 +237,10 @@ const filterKeyHints = new Map<string, string>([
   ["hashtagin", "hashtagin:#ai,#ml"],
   ["tags", "hashtagin:#ai,#ml"],
   ["hashtags", "hashtagin:#ai,#ml"],
-  ["engagement", "engagement:minLikes=100"]
+  ["engagement", "engagement:minLikes=100"],
+  ["since", "since:24h"],
+  ["until", "until:2026-01-01T00:00:00Z"],
+  ["age", "age:<24h"]
 ]);
 
 type FilterSuggestion = {
@@ -296,6 +301,18 @@ const filterSuggestions: ReadonlyArray<FilterSuggestion> = [
     keys: ["engagement"],
     suggestions: ["engagement:minLikes=100"]
   },
+  {
+    keys: ["since"],
+    suggestions: ["since:24h"]
+  },
+  {
+    keys: ["until"],
+    suggestions: ["until:2026-01-01T00:00:00Z"]
+  },
+  {
+    keys: ["age"],
+    suggestions: ["age:<24h"]
+  },
   {
     keys: ["authorin", "authors"],
     suggestions: ["authorin:alice,bob"]
@@ -315,6 +332,7 @@ const defaultFilterExamples = [
   "hashtag:#ai",
   "text:\"hello\""
 ];
+const filterHelpHint = " Tip: run \"skygent filter help\" for all predicates.";
 
 const uniqueSuggestions = (items: ReadonlyArray<string>) =>
   Array.from(new Set(items));
@@ -826,7 +844,8 @@ class Parser {
   constructor(
     private readonly input: string,
     private readonly tokens: ReadonlyArray<Token>,
-    private readonly library: FilterLibraryService
+    private readonly library: FilterLibraryService,
+    private readonly now: Date
   ) {}
 
   parse = (): Effect.Effect<FilterExpr, CliInputError> => {
@@ -1031,7 +1050,7 @@ class Parser {
         const unsupported = unsupportedFilterKeys.get(lower);
         if (unsupported) {
           return yield* self.fail(
-            `Unknown filter type "${value}". ${unsupported}`,
+            `Unknown filter type "${value}". ${unsupported}${filterHelpHint}`,
             token.position
           );
         }
@@ -1043,7 +1062,7 @@ class Parser {
           );
         }
         return yield* self.fail(
-          "Expected a filter expression like 'hashtag:#ai' or 'author:handle'.",
+          `Expected a filter expression like 'hashtag:#ai' or 'author:handle'.${filterHelpHint}`,
           token.position
         );
       }
@@ -1111,6 +1130,8 @@ class Parser {
       const { value: baseValueRaw, valuePosition: basePosition, options } =
         yield* parseValueOptions(self.input, rawValue, valuePosition, optionMode);
       const baseValue = stripQuotes(baseValueRaw);
+      const timeError = (message: string, cause?: unknown) =>
+        failAt(self.input, basePosition, message);
 
       switch (key) {
         case "author":
@@ -1197,7 +1218,10 @@ class Parser {
             case "embeds":
               return { _tag: "HasEmbed" };
             default:
-              return yield* self.fail(`Unknown has: filter "${baseValue}".`, token.position);
+              return yield* self.fail(
+                `Unknown has: filter "${baseValue}". Use images|video|links|media|embed.`,
+                token.position
+              );
           }
         }
         case "engagement": {
@@ -1296,6 +1320,105 @@ class Parser {
           yield* ensureNoUnknownOptions(options, self.input);
           return { _tag: "DateRange", start: range.start, end: range.end };
         }
+        case "since": {
+          if (baseValue.length === 0) {
+            return yield* self.fail(`Missing value for "${key}".`, token.position);
+          }
+          const start = yield* parseTimeInput(baseValue, self.now, {
+            label: "since",
+            onError: timeError
+          });
+          const end = self.now;
+          if (start.getTime() >= end.getTime()) {
+            return yield* self.fail(
+              "Since value must be before now.",
+              basePosition
+            );
+          }
+          yield* ensureNoUnknownOptions(options, self.input);
+          return {
+            _tag: "DateRange",
+            start: yield* self.asTimestamp(start, basePosition),
+            end: yield* self.asTimestamp(end, basePosition)
+          };
+        }
+        case "until": {
+          if (baseValue.length === 0) {
+            return yield* self.fail(`Missing value for "${key}".`, token.position);
+          }
+          const end = yield* parseTimeInput(baseValue, self.now, {
+            label: "until",
+            onError: timeError
+          });
+          const start = new Date(0);
+          if (start.getTime() >= end.getTime()) {
+            return yield* self.fail(
+              "Until value must be after the epoch (1970-01-01T00:00:00Z).",
+              basePosition
+            );
+          }
+          yield* ensureNoUnknownOptions(options, self.input);
+          return {
+            _tag: "DateRange",
+            start: yield* self.asTimestamp(start, basePosition),
+            end: yield* self.asTimestamp(end, basePosition)
+          };
+        }
+        case "age": {
+          if (baseValue.length === 0) {
+            return yield* self.fail(`Missing value for "${key}".`, token.position);
+          }
+          const comparatorMatch = /^(<=|>=|<|>)/.exec(baseValue.trim());
+          const comparator = comparatorMatch?.[1];
+          const durationRaw = comparator
+            ? baseValue.trim().slice(comparator.length).trim()
+            : baseValue.trim();
+          if (durationRaw.length === 0) {
+            return yield* self.fail("Age filter requires a duration.", basePosition);
+          }
+          const duration = yield* parseDurationInput(durationRaw, {
+            label: "age",
+            onError: timeError
+          });
+          const durationMillis = Duration.toMillis(duration);
+          if (durationMillis <= 0) {
+            return yield* self.fail(
+              "Age duration must be greater than zero.",
+              basePosition
+            );
+          }
+          const now = self.now.getTime();
+          if (comparator === ">" || comparator === ">=") {
+            const end = new Date(now - durationMillis);
+            const start = new Date(0);
+            if (start.getTime() >= end.getTime()) {
+              return yield* self.fail(
+                "Age duration is larger than the available timeline.",
+                basePosition
+              );
+            }
+            yield* ensureNoUnknownOptions(options, self.input);
+            return {
+              _tag: "DateRange",
+              start: yield* self.asTimestamp(start, basePosition),
+              end: yield* self.asTimestamp(end, basePosition)
+            };
+          }
+          const start = new Date(now - durationMillis);
+          const end = self.now;
+          if (start.getTime() >= end.getTime()) {
+            return yield* self.fail(
+              "Age duration is larger than the available timeline.",
+              basePosition
+            );
+          }
+          yield* ensureNoUnknownOptions(options, self.input);
+          return {
+            _tag: "DateRange",
+            start: yield* self.asTimestamp(start, basePosition),
+            end: yield* self.asTimestamp(end, basePosition)
+          };
+        }
         case "links":
         case "validlinks":
         case "hasvalidlinks": {
@@ -1344,7 +1467,7 @@ class Parser {
           const unsupported = unsupportedFilterKeys.get(key);
           if (unsupported) {
             return yield* self.fail(
-              `Unknown filter type "${rawKey}". ${unsupported}`,
+              `Unknown filter type "${rawKey}". ${unsupported}${filterHelpHint}`,
               token.position
             );
           }
@@ -1353,7 +1476,7 @@ class Parser {
             ? formatSuggestionHint(suggestions)
             : ` Try "${defaultFilterExamples[0]}", "${defaultFilterExamples[1]}", or "${defaultFilterExamples[2]}".`;
           return yield* self.fail(
-            `Unknown filter type "${rawKey}".${hint}`,
+            `Unknown filter type "${rawKey}".${hint}${filterHelpHint}`,
             token.position
           );
         }
@@ -1365,6 +1488,17 @@ class Parser {
     return Effect.fail(failAt(this.input, position, message));
   }
 
+  private asTimestamp(
+    date: Date,
+    position: number
+  ): Effect.Effect<Timestamp, CliInputError> {
+    return Schema.decodeUnknown(Timestamp)(date).pipe(
+      Effect.mapError((error) =>
+        failAt(this.input, position, `Invalid timestamp: ${formatSchemaError(error)}`)
+      )
+    );
+  }
+
   private peek(): Token | undefined {
     return this.tokens[this.index];
   }
@@ -1405,7 +1539,8 @@ class Parser {
 export const parseFilterDsl = Effect.fn("FilterDsl.parse")((input: string) =>
   Effect.gen(function* () {
     const library = yield* FilterLibrary;
+    const nowMillis = yield* Clock.currentTimeMillis;
     const tokens = yield* tokenize(input);
-    return yield* new Parser(input, tokens, library).parse();
+    return yield* new Parser(input, tokens, library, new Date(nowMillis)).parse();
   })
 );

package/src/cli/filter-errors.ts

@@ -1,5 +1,5 @@
 import { ParseResult } from "effect";
-import { safeParseJson, issueDetails } from "./shared.js";
+import { safeParseJson, issueDetails } from "./parse-errors.js";
 import { formatAgentError, type AgentErrorPayload } from "./errors.js";
 
 const validFilterTags = [
@@ -31,6 +31,7 @@ const validFilterTags = [
 ];
 
 const filterDocs = "docs/filters/README.md";
+const filterHelpHint = "Tip: run \"skygent filter help\" for examples and aliases.";
 
 
 const getTag = (raw: string): string | undefined => {
@@ -48,13 +49,18 @@ const getTag = (raw: string): string | undefined => {
 const hasPath = (issue: { readonly path: ReadonlyArray<unknown> }, key: string) =>
   issue.path.length === 1 && issue.path[0] === key;
 
+const withHelpHint = (payload: Omit<AgentErrorPayload, "error">) => ({
+  ...payload,
+  details: payload.details ? [...payload.details, filterHelpHint] : [filterHelpHint]
+});
+
 const validationError = (
   payload: Omit<AgentErrorPayload, "error">
-) => formatAgentError({ error: "FilterValidationError", ...payload });
+) => formatAgentError({ error: "FilterValidationError", ...withHelpHint(payload) });
 
 const jsonParseError = (
   payload: Omit<AgentErrorPayload, "error">
-) => formatAgentError({ error: "FilterJsonParseError", ...payload });
+) => formatAgentError({ error: "FilterJsonParseError", ...withHelpHint(payload) });
 
 
 export const formatFilterParseError = (error: ParseResult.ParseError, raw: string): string => {

package/src/cli/filter-help.ts

@@ -24,6 +24,7 @@ export const filterJsonDescription = (extra?: string) =>
     "Filter expression as JSON string.",
     "Sync/query filters run at ingestion or query time; store config filters are materialized views.",
     ...(extra ? [extra] : []),
+    "Tip: run \"skygent filter help\" for all predicates and aliases.",
     "",
     filterJsonExamples
   ].join("\n");
@@ -31,6 +32,7 @@ export const filterJsonDescription = (extra?: string) =>
 const filterDslExamples = [
   "Examples:",
   "  hashtag:#ai AND author:user.bsky.social",
+  "  from:alice.bsky.social",
   "  authorin:alice.bsky.social,bob.bsky.social",
   "  hashtagin:#tech,#coding",
   "  contains:\"typescript\",caseSensitive=false",
@@ -40,9 +42,13 @@ const filterDslExamples = [
   "  engagement:minLikes=100,minReplies=5",
   "  hasmedia",
   "  hasembed",
+  "  has:images",
   "  language:en,es",
   "  @tech AND author:user.bsky.social",
   "  date:2024-01-01T00:00:00Z..2024-01-31T00:00:00Z",
+  "  since:24h",
+  "  until:2024-01-15",
+  "  age:<72h",
   "  links:onError=exclude",
   "  trending:#ai,onError=include",
   "  (hashtag:#ai OR hashtag:#ml) AND author:user.bsky.social",
@@ -65,6 +71,7 @@ export const filterDslDescription = () =>
     "Options are comma-separated (no spaces); quote values with spaces.",
     "Lists use commas (e.g. authorin:alice,bob). Named filters use @name.",
     "Defaults: onError defaults to include for trending and exclude for links.",
+    "Tip: run \"skygent filter help\" for all predicates and aliases.",
     "",
     filterDslExamples
   ].join("\n");

package/src/cli/filter-input.ts

@@ -1,4 +1,5 @@
 import { Effect, Option } from "effect";
+import type { Clock as ClockService } from "effect/Clock";
 import { FilterExprSchema, all } from "../domain/filter.js";
 import type { FilterExpr } from "../domain/filter.js";
 import type { FilterLibrary } from "../services/filter-library.js";
@@ -16,7 +17,7 @@ const conflictError = (filter: boolean, filterJson: boolean) =>
 export const parseFilterExpr = (
   filter: Option.Option<string>,
   filterJson: Option.Option<string>
-): Effect.Effect<FilterExpr, CliInputError | CliJsonError, FilterLibrary> =>
+): Effect.Effect<FilterExpr, CliInputError | CliJsonError, FilterLibrary | ClockService> =>
   Option.match(filter, {
     onNone: () =>
       Option.match(filterJson, {
@@ -36,7 +37,7 @@ export const parseFilterExpr = (
 export const parseOptionalFilterExpr = (
   filter: Option.Option<string>,
   filterJson: Option.Option<string>
-): Effect.Effect<Option.Option<FilterExpr>, CliInputError | CliJsonError, FilterLibrary> =>
+): Effect.Effect<Option.Option<FilterExpr>, CliInputError | CliJsonError, FilterLibrary | ClockService> =>
   Option.match(filter, {
     onNone: () =>
       Option.match(filterJson, {

package/src/cli/filter.ts

@@ -24,6 +24,7 @@ import { renderTableLegacy } from "./doc/table.js";
 import { withExamples } from "./help.js";
 import { filterOption, filterJsonOption } from "./shared-options.js";
 import { jsonTableFormats, resolveOutputFormat, textJsonFormats } from "./output-format.js";
+import { filterDslDescription, filterJsonDescription } from "./filter-help.js";
 
 const filterNameArg = Args.text({ name: "name" }).pipe(
   Args.withSchema(StoreName),
@@ -42,6 +43,15 @@ const storeOption = Options.text("store").pipe(
   Options.withSchema(StoreName),
   Options.withDescription("Store name to sample for benchmarking")
 );
+const storeTestOption = Options.text("store").pipe(
+  Options.withSchema(StoreName),
+  Options.withDescription("Store name to sample for filter testing"),
+  Options.optional
+);
+const testLimitOption = Options.integer("limit").pipe(
+  Options.withDescription("Number of posts to evaluate (default: 100)"),
+  Options.optional
+);
 const sampleSizeOption = Options.integer("sample-size").pipe(
   Options.withDescription("Number of posts to evaluate (default: 1000)"),
   Options.optional
@@ -267,17 +277,74 @@ export const filterTest = Command.make(
     filterJson: filterJsonOption,
     postJson: postJsonOption,
     postUri: postUriOption,
+    store: storeTestOption,
+    limit: testLimitOption,
     format: testFormatOption
   },
-  ({ filter, filterJson, postJson, postUri, format }) =>
+  ({ filter, filterJson, postJson, postUri, store, limit, format }) =>
     Effect.gen(function* () {
       yield* requireFilterExpr(filter, filterJson);
       const expr = yield* parseFilterExpr(filter, filterJson);
       const runtime = yield* FilterRuntime;
+      const outputFormat = Option.getOrElse(format, () => "text" as const);
+      if (Option.isSome(store)) {
+        if (Option.isSome(postJson) || Option.isSome(postUri)) {
+          return yield* CliInputError.make({
+            message: "Use either --store or --post-json/--post-uri, not both.",
+            cause: { store: store.value, postJson, postUri }
+          });
+        }
+        if (Option.isSome(limit) && limit.value <= 0) {
+          return yield* CliInputError.make({
+            message: "--limit must be a positive integer.",
+            cause: { limit: limit.value }
+          });
+        }
+        const storeRef = yield* storeOptions.loadStoreRef(store.value);
+        const index = yield* StoreIndex;
+        const evaluateBatch = yield* runtime.evaluateBatch(expr);
+        const sampleLimit = Option.getOrElse(limit, () => 100);
+        const query = StoreQuery.make({ scanLimit: sampleLimit, order: "desc" });
+        const stream = index.query(storeRef, query);
+        const result = yield* stream.pipe(
+          Stream.grouped(50),
+          Stream.runFoldEffect(
+            { processed: 0, matched: 0 },
+            (state, batch) =>
+              evaluateBatch(batch).pipe(
+                Effect.map((results) => {
+                  const processed = state.processed + Chunk.size(batch);
+                  const matched =
+                    state.matched +
+                    Chunk.toReadonlyArray(results).filter(Boolean).length;
+                  return { processed, matched };
+                })
+              )
+          )
+        );
+        if (outputFormat === "json") {
+          yield* writeJson({
+            store: storeRef.name,
+            processed: result.processed,
+            matched: result.matched,
+            limit: sampleLimit,
+            filter: expr,
+            filterText: formatFilterExpr(expr)
+          });
+          return;
+        }
+        const lines = [
+          `Matched: ${result.matched}/${result.processed}`,
+          `Store: ${storeRef.name}`,
+          `Filter: ${formatFilterExpr(expr)}`
+        ];
+        yield* writeText(lines.join("\n"));
+        return;
+      }
+
       const predicate = yield* runtime.evaluate(expr);
       const post = yield* loadPost(postJson, postUri);
       const ok = yield* predicate(post);
-      const outputFormat = Option.getOrElse(format, () => "text" as const);
       if (outputFormat === "json") {
         yield* writeJson({
           ok,
@@ -297,8 +364,9 @@ export const filterTest = Command.make(
     })
 ).pipe(
   Command.withDescription(
-    withExamples("Test a filter against a single post", [
-      "skygent filter test --filter 'hashtag:#ai' --post-uri at://did:plc:example/app.bsky.feed.post/xyz"
+    withExamples("Test a filter against a post or store sample", [
+      "skygent filter test --filter 'hashtag:#ai' --post-uri at://did:plc:example/app.bsky.feed.post/xyz",
+      "skygent filter test --filter 'engagement:minLikes=10' --store my-store --limit 100"
     ])
   )
 );
@@ -414,8 +482,20 @@ export const filterDescribe = Command.make(
   )
 );
 
+export const filterHelp = Command.make("help", {}, () =>
+  Effect.gen(function* () {
+    const body = [filterDslDescription(), "", filterJsonDescription()].join("\n");
+    yield* writeText(body);
+  })
+).pipe(
+  Command.withDescription(
+    withExamples("Show filter DSL and JSON help", ["skygent filter help"])
+  )
+);
+
 export const filterCommand = Command.make("filter", {}).pipe(
   Command.withSubcommands([
+    filterHelp,
     filterList,
     filterShow,
     filterCreate,