scout

The single entry point for the Scout Application Capability Intelligence Platform

One package. One import. Everything you need to annotate your Flutter app's capabilities and work with the generated manifest — with zero transitive dependencies.

import 'package:scout/scout.dart';

---

What you get

1. Annotations for your production code

Mark screens and service methods so Scout understands your app:

@Capability(
  id: 'mark_attendance',
  label: 'Mark Attendance',
  category: 'Attendance Management',
  description: 'Record attendance for a class session. Requires class ID, date, and records.',
  permissions: ['attendance:write'],
  preconditions: ['authenticated_user', 'selected_class'],
  owner: 'attendance-team',
)
class MarkAttendanceScreen extends StatelessWidget { ... }

@Permission(
  id: 'attendance:write',
  label: 'Write Attendance',
  roles: ['teacher', 'admin'],
)
class AttendanceWritePermission {}

@Workflow(
  id: 'fee_payment_workflow',
  label: 'Pay Fees',
  steps: [
    WorkflowStep(order: 1, capabilityId: 'view_fee_structure'),
    WorkflowStep(order: 2, capabilityId: 'view_fee_dues'),
    WorkflowStep(order: 3, capabilityId: 'pay_fees_online'),
    WorkflowStep(order: 4, capabilityId: 'download_fee_receipt'),
  ],
)
class FeePaymentFlow {}

2. A typed model for reading scout.manifest.json

Consume the generated manifest in CLI tools, test assertions, custom integrations:

import 'dart:convert';
import 'dart:io';
import 'package:scout/scout.dart';

final json = jsonDecode(File('.scout/manifest.json').readAsStringSync());
final manifest = ScoutManifest.fromJson(json as Map<String, dynamic>);

// What can a teacher do?
final teacherCapabilities = manifest.capabilitiesForRole('teacher');
print(teacherCapabilities.map((c) => c.label).join('\n'));

// Find a specific capability
final cap = manifest.capabilityById('mark_attendance');
print(cap?.aiTool?.description);

// Access routes
for (final route in manifest.routes) {
  print('${route.path} [${route.access}]');
}

---

Annotations reference

Annotation	Place on	Purpose
@Capability	screen classes, service methods	Declare a named user capability
@Permission	any class	Declare a named permission for the registry
@Workflow	any class	Declare a multi-step capability sequence
@FeatureFlag	screen classes	Gate a capability behind a feature flag
@Owner	any class	Declare team ownership for diff notifications

@Capability fields

Field	Type	Required	Description
id	String	yes	Unique snake_case verb_noun identifier
label	String	yes	Human-readable display name
category	String	yes	Functional grouping (e.g. 'Attendance Management')
description	String?	—	Plain-English description for AI systems
permissions	List<String>	—	Required permission IDs (e.g. ['attendance:write'])
preconditions	List<String>	—	Required state keys (e.g. ['authenticated_user'])
relatedCapabilities	List<String>	—	Related capability IDs for AI navigation
analyticsEvent	String?	—	Analytics event emitted on use
owner	String?	—	Responsible team/individual
gdpr	GdprClass	—	none / personal / sensitive
offlineCapable	bool	—	Can function without network?

---

ScoutManifest model

The ScoutManifest class and its associated types provide a complete typed representation of scout.manifest.json. All classes have fromJson / toJson methods.

Key types

Class	Description
ScoutManifest	Top-level manifest
ScoutApp	App metadata (name, version, roles, base URL)
CapabilityNode	A single capability entry
AiTool	OpenAI-compatible tool definition derived from a capability
RouteNode	A route from scout_router analysis
ApiEndpointNode	An endpoint from scout_openapi analysis
SchemaNode	A data model schema
PermissionNode	A declared permission
FeatureFlagNode	A feature flag
WorkflowNode / WorkflowStep	A multi-step workflow

Convenience methods on ScoutManifest

// Capabilities visible to a role (filtered by permission→role mapping)
manifest.capabilitiesForRole('teacher')

// Lookup by ID
manifest.capabilityById('mark_attendance')
manifest.routeById('attendance_mark_route')

---

Installation

# pubspec.yaml
dependencies:
  scout: ^0.1.0

If you only need the annotations (no manifest model), use scout_annotations instead — it's a strict subset with the same zero-dep guarantee.

---

The Scout workflow

# 1. Annotate your screens and services (this package)

# 2. Generate the capability graph
dart run build_runner build

# 3. Inspect the result
scout scan          # analyse + write .scout/manifest.json
scout serve         # MCP + REST server on localhost:4242
scout validate      # CI gate — fails on unlinked routes
scout diff          # detect breaking capability changes

---

Part of Scout

The full Scout platform consists of:

Package	Role
scout (this)	Annotations + manifest model — the developer entry point
scout_annotations	Annotations only, for production code with strict zero-dep requirements
scout_openapi	build_runner plugin: Dart → OpenAPI 3.0 spec
scout_router	build_runner plugin: go_router → route manifest
scout_builder	Orchestrates all passes → scout.manifest.json
scout_cli	The scout command-line tool (14 commands)
scout_mcp	MCP + REST server for AI agent integration

---

License

MIT