Skip to content

docs(exfil): document watch rule schema and pre-push validate#238

Draft
maximelb wants to merge 1 commit into
masterfrom
docs/exfil-watch-schema-and-validate
Draft

docs(exfil): document watch rule schema and pre-push validate#238
maximelb wants to merge 1 commit into
masterfrom
docs/exfil-watch-schema-and-validate

Conversation

@maximelb
Copy link
Copy Markdown
Contributor

Summary

A recent support case followed the pattern: customer pushed an Exfil config containing a malformed Watch Rule, the push timed out without surfacing the actual schema error, and they had to wait for a human to diagnose it. The customer's own feedback was "work on the docs and the error handling" — this PR is the docs half.

Changes

In docs/5-integrations/extensions/limacharlie/exfil.md:

  1. Watch Rule Fields reference table (under Using the Exfil Extension): per-field type and required/optional flag, with a "common gotcha" callout that path, filters.platforms, and filters.tags must be YAML lists even when they only have one value.

  2. Configuration via Hive section: a complete, valid Watch Rule YAML example using the extension_config hive, demonstrating the list form for path and the nested filters block. Matches the pattern already established in the feedback and usage-alerts docs.

  3. Validate Before Pushing subsection: documents the limacharlie hive validate --hive-name extension_config --key ext-exfil workflow as the read-only pre-flight check, including what an empty {} response means and the fact that validate never modifies stored config.

No customer-supplied data or identifiers are included; all examples use generic field values.

Test plan

  • Render docs locally with mkdocs serve and confirm the new sections appear in the expected order in the left nav
  • Verify table renders correctly in the rendered site (some markdown engines disagree on pipe-table alignment)
  • Spot-check that the YAML example would actually pass limacharlie hive validate against a current ext-exfil schema

🤖 Generated with Claude Code

A recent support case stemmed from a Watch Rule config that mixed scalar
and list types for required fields. The current docs only describe the
fields conceptually and the CLI's pre-push validate workflow isn't
documented anywhere, so customers can't self-serve when the underlying
schema rejects their config.

- Add a Watch Rule Fields reference table showing the expected type
  (string vs list) and which fields are required.
- Add a "Configuration via Hive" section with a complete, valid YAML
  example using the list form for path/filters.platforms/filters.tags.
- Add a "Validate Before Pushing" section documenting
  limacharlie hive validate as the read-only pre-flight check that
  returns '{}' on success and a description of the failure otherwise.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant