feat: guided monitor setup from targets to an active baseline #1266

Outcome

Help a unit administrator or operator create a correctly scoped monitoring job, understand its expected probe work before saving, and follow its first scan through baseline learning. The same flow supports the first job and subsequent jobs. This advances adoption and everyday usability after the v0.31.0 notification provider builder.

The product journey is Targets → Coverage → Schedule and alerts → Review and create → Scan and baseline progress. Existing job editing, scanner policies, notification encryption, and baseline semantics remain authoritative.

Verified starting point

Plan baseline: aaa2b4351e1e418912c5575e1d6c2d20e9033e1e / v0.31.0.

• src/pages/JobEditor.tsx already has defaults, schedule presets, profile selection, routing, conflict handling, and unsaved-draft protection. It presents these together and sends newly created jobs back to the list.
• internal/config/config.go already estimates bounded host/probe work without DNS resolution or scanning. The current editor exposes work estimates after saving.
• internal/web/job_handlers.go prepares new jobs, resolves profile revisions, validates routing, creates an audited record, and returns the job.
• src/pages/JobDetail.tsx already handles accepted, queued, running, and rapidly completed scan requests. Reuse this lifecycle rather than creating a second monitor engine.
• src/components/NotificationDestinationConfig.tsx supplies the released provider form.

This is a repository-supported usability opportunity. Actual abandonment rates and recurring user pain were not supplied; do not invent improvement percentages.

Product decisions

1. Make /jobs/new the guided creation route; expose the full existing new-job editor at /jobs/new/advanced. Keep /jobs/:id/edit and all existing saved-job APIs compatible. Transfer non-secret draft data between creation modes without losing advanced values; mark advanced configuration accurately in review.
2. Keep existing new-job defaults, including two baseline samples, current confirmation threshold, timezone behavior, timing, limits, and explicit high-cost approval. Default full TCP uses the current built-in Naabu→Nmap profile. A chosen-port TCP scope uses Nmap and explicitly declares partial coverage. UDP remains an optional Nmap configuration; do not label partial scans as full coverage.
3. Reuse cadence presets and schedule suggestions, with visible timezone and the actual next-run semantics. A schedule does not imply that the initial scan or baseline is already complete.
4. Administrators may create/test a destination inside the flow using the existing notification APIs and account-password confirmation. Operators select available destinations only. Show an explicit choice to continue without alerts. A successfully saved destination is a separate durable resource even if the monitor draft is later canceled; do not silently delete it.
5. Credentials and account passwords stay in transient component state. Never put them in route state, query keys, URLs, browser storage, analytics, issue fixtures, or logs. Clear them after save/cancel/unmount.
6. The preview validates the same creation policy, canonical configuration, profile revision, routing, exclusions, and tenant budget. It performs no scan, DNS lookup, job write, audit write, scheduling, notification send, or SSE publication. Preview is advisory; create and run revalidate current state.
7. Final review offers Create and start first scan and Create without starting. Creation and scan start are separate existing operations. If run fails after create succeeds, preserve and open the created job with a retry action; retrying run must never recreate the job. Do not automatically retry a create request whose outcome is unknown.
8. Derive learning/ready/stalled state from persisted job and scan data. Preserve failed/incomplete observation behavior, explicit baseline approval controls, baseline samples, change confirmations, cancellation, and resumable work. Offer another sample explicitly or explain the next scheduled run; do not auto-run a loop or auto-approve results.

Architecture

• Add POST /api/v1/jobs/preview and typed previewJob client support. Share creation preparation and the store's installed exclusion validation rather than maintaining a weaker parallel validator.
• Extract narrowly scoped shared frontend defaults, schema, payload conversion, and draft state. Keep advanced editing and revision/rebaseline contracts intact.
• Build MonitorSetup from existing API capabilities, profile/destination lists, forms, and schedule guidance.
• Add a reusable next-action panel to job detail, using existing queries/live updates and existing scan-request handling. It remains reconstructable after navigation, refresh, and restart without an onboarding-state table.
• No new dependency, schema migration, runtime configuration, scanner command surface, or external service is required.

Implementation work

Completion checklist

• feat: preview draft job policy, scope, and unit probe budget #1267
• refactor: share job creation defaults, payload conversion, and draft state #1268
• feat: add guided monitor creation with scope and alert review #1269
• feat: guide created jobs through first scan and baseline learning #1270
• test: qualify guided monitor setup and verify deployed user guides #1271

The backend preview and shared frontend extraction can begin independently. Guided setup needs both; baseline guidance follows the setup integration. Qualification closes the journey. Each task includes focused tests and documentation in its own change; final qualification is not a reason to postpone those obligations.

Acceptance criteria

• A new administrator can complete one connected journey from authorized target input to a created job, a useful first result, and understandable baseline progress.
• An operator can create/run jobs and select destinations without gaining destination management, profile management, or high-cost approval.
• Preview reflects actual scanner scope, policy, pinned profile revision, routing, and unit budgets before creation. Unknown DNS expansion and data-dependent work remain explicit.
• Guided/advanced creation switch without draft loss or secret persistence; saved-job editing and existing clients remain compatible.
• Duplicate clicks, stale preview responses, create/run failures, queueing, cancellation, missing resources, and refresh are handled without false success or duplicate job creation.
• Baseline learning, zero positive ports, stalled/incomplete scans, and active baseline are distinguished truthfully.
• The existing backend role/tenant matrices and frontend/browser regression suites pass with meaningful coverage for new paths.
• First-scan, jobs/scanning, notifications, API compatibility, and affected quick-start/security guidance are updated; the corresponding documentation deployment is verified.

Validation and delivery

Use the checked-in Go/Node versions. Go changes require correct-version gofmt, go vet ./..., and go test -race -timeout=25m ./.... Console changes require npm run lint, npm run build, and npm run test:coverage; browser behavior requires npm run test:e2e. Run the normal CI/security and diff-coverage gates. Use fixture databases and authorized controlled listeners. Build and review the documentation with npm --prefix docs ci and npm --prefix docs run build, then verify its deployed pages.

Deliver in focused PRs with docs alongside behavior. The preview/shared extraction can merge before the guided route goes live; retain the existing creation entry point until its replacement passes acceptance checks. Do not expand scope to scanner execution, storage schema, or release-pipeline rewrites. Publication itself requires the existing tag-only immutable-candidate gates and a separately authorized release action.

Scope estimate

Large: approximately 24–42 engineering hours (3–6 working days) including regression coverage, browser review, and docs, subject to refinement after shared-form extraction. Existing code already provides the engine; the effort is in avoiding configuration drift and handling realistic lifecycle states.

Success evidence

Use controlled task-based review to record completion, navigation steps, configuration mistakes, and comprehension of coverage/baseline state. Compare first-job and repeat-job setup with the existing editor. No telemetry service is required.