Files
kandev/docs/public
João Salavisa 37b56ba11c feat(automations): reliable cron scheduling and webhook-driven push/CI triggers (#1972)
* feat(automations): reliable cron scheduling and webhook-driven push/CI triggers

Automations were "wounded": cron schedules mishandled timezones and some
never fired, and the GitHub push/CI trigger types were coming-soon stubs.

Cron (fix):
- The scheduler reduced every cron expression to a fixed interval derived
  only from a */N step in the minute/hour field, so any pinned schedule
  (0 9 * * *, 30 14 * * *, weekday ranges, day-of-month) never fired, and
  the configured timezone was parsed but never used.
- Replace the interval approximation with robfig/cron/v3: shouldFire now
  computes the true next fire time in the configured timezone (DST-aware,
  defaulting to UTC for host-independence), anchored to last-evaluated or
  creation time. Dead interval-parsing helpers and shorthand constants
  removed.

GitHub push + CI triggers (feat):
- Implement push and CI-failure triggers end to end via the existing
  per-workspace GitHub App webhook plumbing (#1810): the HMAC-verified
  webhook service now parses push and completed check_run events, resolves
  the installation to its workspaces, and publishes normalized bus events.
- A new automation subscriber matches enabled github_push / github_ci
  triggers by workspace + repo + branch/conclusion/check-name filters and
  fires them (deduped by commit SHA / check-run id). The old poll-based
  stub evaluators are removed; the PR poll path is unchanged.
- Subscribe the App manifest to push/check_run and enable both trigger
  types in the registry (CI defaults to the failure conclusion).

Docs:
- Update docs/public/feature-status.md and automation-and-mcp.md so the
  cron and push/CI rows reflect shipped reality.

Tests: regression tests pin the previously-never-firing cron shapes,
timezone/DST behavior, and host-independence; backend tests cover the
webhook parse->publish and subscriber match/fire/dedup flows for both
push and CI-failure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(automations): populate push.message and ci.url placeholders in fired trigger data

Address PR review blockers: the default push and CI automation prompts
reference {{push.message}} and {{ci.url}}, which the interpolator maps to
data["message"] / data["html_url"] — but the webhook subscriber never
populated those fields, so both always rendered empty.

- Parse head_commit.message (push) and check_run.html_url (CI) in the
  GitHub webhook service and carry them on the published bus payloads.
- Include "message" / "html_url" in the fired trigger data so the
  placeholders resolve; extend the webhook and subscriber tests to assert
  both flow through end to end.

Non-blocking review cleanups:
- Replace the misleading reuse of matchesAuthors for CI conclusions/check
  names with a clearly-named matchesFilterValue helper.
- Drop dead context.Background() line and its unused import from the cron
  regression test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(automations): scope webhook triggers to active installs and per-branch dedup

Address CodeRabbit review on the push/CI webhook triggers:

- Security: resolveWorkspaceIDs now only returns connections whose status is
  active, so a suspended or revoked GitHub App installation can no longer fire
  push/CI automations.
- Correctness: include the branch in the push dedup key
  (push:owner/name@branch@sha) so the same commit pushed to two matching
  branches fires once per branch instead of being suppressed.
- Correctness: add an optional head-branch filter to github_ci triggers and
  gate CI matching on it, matching the push trigger's branch-scoping.
- Stability: make the webhook subscriber's Start retryable — a subscription
  failure rolls back partial subscriptions and leaves the subscriber
  un-started so a later Start re-attempts, instead of permanently disabling
  push/CI processing.
- Tests: cover multi-connection workspace resolution (dedup + inactive
  filtering), per-branch push dedup, and CI branch filtering.
- Docs: note the CI branch filter and per-branch push dedup.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(automations): cover webhook subscriber Start retry-after-failure path

Add TestGitHubWebhookSubscriberStartRetryableAfterFailure with a minimal
flaky bus whose second Subscribe fails, pinning the retry contract: a
subscription failure rolls back the partial subscription and leaves the
subscriber un-started, and a later Start re-attempts and succeeds.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-27 10:24:57 +01:00
..

Contributing to the Public Docs

docs/public/ is the source for kandev.ai/docs. Pull requests validate this tree. After a push to main, .github/workflows/notify-docs.yml validates it again and, when the deploy hook is configured, calls Landing; a validation failure prevents publication.

The published docs have two audiences:

  • Use Kandev covers product tasks, configuration, limits, security, and operations.
  • Contribute to Kandev covers code ownership, development, testing, extension points, releases, and docs maintenance.

Keep implementation detail in contributor pages. A user guide should explain the supported behavior and link here when internal context is useful.

Update an existing page

Edit the Markdown source and verify every command, setting, label, default, platform claim, and screenshot against current source or tests. Preserve the filename when possible: it is the public slug.

Use source-relative links such as [CLI](cli.md). Publication rewrites links between public pages to /docs/... and links to repository files outside docs/public/ to GitHub. Do not use site-root links or local machine paths.

State whether behavior is default, optional, platform-dependent, experimental, feature-flagged, internal, or still in progress. An ADR, spec, hidden route, or source package is not evidence that a feature is generally available.

Mark experimental content

Use page-level status when the whole guide describes an experimental surface:

---
title: "Kubernetes"
description: "Deploy Kandev to Kubernetes."
status: experimental
---

The docs header renders a visible status callout from that frontmatter. To invoke this experimental page indicator, use the exact value experimental; omit status for stable pages. Source validation rejects other page-status values. The separate stable, beta, and experimental values in coverage.json describe inventory stability and do not create page badges.

Use a section-level indicator when a stable guide contains one experimental capability. Keep this source syntax as Markdown so older renderers and GitHub still show an explicit callout; the publication layer upgrades it to the styled status component:

## Office dependencies

> [!EXPERIMENTAL]
> Office is feature-flagged and its dependency editor is not stable yet.

When Office is enabled, it can record blocked-by relationships between tasks. Use parent/child structure and workflow gates for the supported regular-Kanban path.

Place the indicator immediately after a descriptive heading that names the experimental capability, then follow it with the instructions or behavior it qualifies. Explain the enabling condition, current limit, and supported alternative. Do not drop a warning between otherwise stable paragraphs or create a standalone status section whose only content is the warning. The publication pipeline converts the callout to FeatureStatus and opts the generated page into MDX automatically.

Add a page

  1. Search existing pages and choose Use Kandev or Contribute to Kandev.

  2. Create a lowercase, kebab-case Markdown file in docs/public/. The filename becomes the stable route; custom-executors.md publishes as /docs/custom-executors.

  3. Add non-empty title and description frontmatter, then one level-one heading:

    ---
    title: "Custom Executors"
    description: "Configure a custom executor for Kandev tasks."
    ---
    
    # Custom Executors
    
  4. Add the slug, without .md, exactly once to docs/public/meta.json under the correct audience heading. Its position controls sidebar order. README.md is the maintenance guide and is not a published page.

  5. Add the page to at least one area in docs/public/coverage.json, with current implementation and test evidence.

  6. Link the page from the relevant overview and neighboring guides.

  7. Include prerequisites, a concrete workflow, exact configuration, failure modes or limits, and related pages where applicable.

The validator rejects missing frontmatter, pages absent from navigation or coverage, duplicate or unknown navigation entries, broken local files or heading fragments, missing assets, and site-root links.

Maintain feature coverage

docs/public/coverage.json is the source-backed map from shipped product areas to their user, operator, contributor, or integrator documentation. Every area cites concrete source and test files. The validator also discovers every static Settings route and registered Kandev MCP tool, then requires each one to have exactly one coverage owner or an explicit exclusion with a reason.

When behavior changes:

  1. Update the owning page and its support boundary.
  2. Update the area's source or test evidence when ownership moved.
  3. Assign a new Settings route or MCP tool to the appropriate area.
  4. Add a new area only when the behavior has a distinct audience, stability, and documentation owner.

Do not use the inventory to claim that a route, package, ADR, test harness, or feature flag is generally available. The page must still explain whether the user-facing behavior is stable, dependency-bound, limited, experimental, or unavailable.

Assets and diagrams

  • Store product screenshots under docs/screenshots/ and reference them relatively.
  • Do not hotlink mutable third-party images or commit temporary capture output.
  • Mermaid diagrams are supported. Keep them readable at docs-column width and explain the essential result in prose.
  • Prefer text and commands when the UI changes frequently.

Use a short focused video only when motion or interaction order communicates something that prose and a still image cannot. Store reviewed deliverables under docs/public/media/feature-guides/ as a WebM, an H.264 MP4 fallback, and a WebP poster. Keep raw captures, browser profiles, and temporary encoder output outside the repository.

Embed the local sources with the publication component:

<DocsVideo
  webm="./media/feature-guides/review.webm"
  mp4="./media/feature-guides/review.mp4"
  poster="./media/feature-guides/review.webp"
  title="Review a focused diff"
  caption="Inspect a changed line and leave feedback for the agent."
/>

Videos must show current isolated test data, avoid real credentials and production repositories, use native controls, and remain understandable from the poster and caption. Prefer a compact view that follows the relevant cursor or touch target over a wide application recording. Keep manifest.json and NOTES.txt beside the reviewed triplets. Source validation checks accepted QA status, the 960x600/25fps/no-audio delivery contract, page and section ownership, complete embeds, byte counts, SHA-256 hashes, and orphaned files. Do not add Markdown files under docs/public/media/ because public Markdown is treated as a page.

Validate the source

Run the dependency-free checks from the Kandev repository root:

node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs

make test-scripts runs the validator's unit tests among other repository script tests; it does not replace the live validation command above.

Verify the Landing publication build

With kdlbs/landing checked out beside kandev, use Landing's documented Node 24.12.0 and pnpm 10.29.3 prerequisites and build the same root-plus-docs artifact deployed to Cloudflare Pages:

cd ../landing
pnpm install --frozen-lockfile
KANDEV_DOCS_SOURCE_PATH="$(cd ../kandev && pwd)/docs" pnpm build:pages

KANDEV_DOCS_SOURCE_PATH makes Landing fetch the local public pages instead of GitHub. Pass an absolute path because the docs package runs its prebuild from landing/apps/docs. The build copies only pages named by meta.json, rewrites links, and builds both the landing site and docs route. Do not commit generated Landing content, .next, or out directories.

Before review, confirm:

  • each new or renamed page appears exactly once in meta.json;
  • links resolve relative to their source file;
  • claims are supported by current code, tests, or workflows;
  • conditional support and platform limits are explicit;
  • source validation and, for publication-sensitive changes, the Landing build pass.