### Setup workspace

Source: https://archipelago.banuacoder.com/docs/guide/monorepo-toolkit.html

Performs initial workspace configuration including dependency installation and code generation.

```bash
melos run workspace:setup
```

--------------------------------

### Mason Brick Installation

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-app-scaffold.html

Instructions on how to install the `app_scaffold` Mason brick for enhanced scaffolding capabilities.

```APIDOC
## Mason Brick Installation

### Description
To use the Mason-based scaffolding (recommended), install the `app_scaffold` brick first. This provides the most complete output with all Fastlane files, CI configs, and platform-specific setup.

### Method
`mason add`

### Usage Examples
```bash
# From mason.yaml (if configured in the workspace)
# mason add app_scaffold

# From a git repository
# mason add app_scaffold --git-url https://github.com/banua-coder/archipelago

# Globally
# mason add -g app_scaffold
```

### Mason CLI Installation
If Mason is not installed at all, install it with:
```bash
dart pub global activate mason_cli
```
```

--------------------------------

### Implement Initialization Logic

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-initializer-skeleton.html

Add your specific setup code within the `initialize` method of your custom initializer. This example shows initializing an analytics client.

```dart
class AnalyticsInitializer extends Initializer {
  @override
  Future<void> initialize() async {
    final analytics = GetIt.I<AnalyticsClient>();
    await analytics.init();
    await analytics.identifyUser();
  }
}
```

--------------------------------

### Archipelago Project Configuration Example

Source: https://archipelago.banuacoder.com/docs/guide/getting-started.html

An example JSON configuration file for creating a new Archipelago project, defining organization, app names, bundle IDs, and features.

```json
{
  "@org": "Your organization name (used for package prefixes)",
  "org": "acme",

  "@app_name": "The Flutter app name (snake_case)",
  "app_name": "my_app",

  "@app_display_name": "Human-readable app name shown to users",
  "app_display_name": "My App",

  "@bundle_id_prefix": "Reverse domain for iOS/Android bundle ID",
  "bundle_id_prefix": "com.acme",

  "@features": "Initial features to generate (comma-separated)",
  "features": "auth,home,settings"
}
```

--------------------------------

### Generate network_sdk (Interactive)

Source: https://archipelago.banuacoder.com/docs/bricks/network-sdk.html

Use this command for interactive generation of the network_sdk. No setup is required beyond having the archipelago tool installed.

```bash
archipelago generate network_sdk
```

--------------------------------

### Installation

Source: https://archipelago.banuacoder.com/docs/cli

Install the Archipelago CLI globally using Dart's pub tool.

```APIDOC
## Installation

Install the Archipelago CLI globally using Dart's pub tool.

### Method
```bash
dart pub global activate archipelago_cli
```
```

--------------------------------

### Install Mason CLI

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-app-scaffold.html

Command to install the Mason CLI globally if not already present.

```bash
dart pub global activate mason_cli
```

--------------------------------

### Configuration Template

Source: https://archipelago.banuacoder.com/docs/bricks/flutter-modular-monorepo.html

Example JSON configuration file for defining project variables.

```json
{
  "@appName": "The name of your application",
  "appName": "MyApp",
  "@organization": "The name of your organization",
  "organization": "MyCompany",
  "@domain": "Your organization's top-level domain",
  "domain": "com",
  "@prefix": "Prefix for project components (e.g., 'App' for AppButton)",
  "prefix": "App",
  "@prefixCasing": "Casing style for the prefix (upperCase | pascalCase)",
  "prefixCasing": "pascalCase",
  "@gitProvider": "Git provider for CI/CD workflows (github | gitlab)",
  "gitProvider": "github",
  "@networkLibrary": "HTTP client library (dio | http)",
  "networkLibrary": "dio",
  "@isUsingWebSocket": "Include WebSocket SDK",
  "isUsingWebSocket": false,
  "@websocketLibrary": "WebSocket library if using WebSocket (dart | phoenix)",
  "websocketLibrary": "dart",
  "@isUsingFirebase": "Using Firebase",
  "isUsingFirebase": false,
  "@isUsingAnalytics": "Include Analytics SDK",
  "isUsingAnalytics": false,
  "@isUsingFeatureFlags": "Include Feature Flags SDK",
  "isUsingFeatureFlags": false,
  "@stateManagement": "State management solution (bloc | provider | riverpod)",
  "stateManagement": "bloc",
  "@includeGenerated": "Include generated files in Git",
  "includeGenerated": false
}
```

--------------------------------

### Example Dependency Tree Output

Source: https://archipelago.banuacoder.com/docs/tutorials/toolkit-dependency-graph.html

An example of the text-based tree output showing package hierarchy and dependencies.

```text
app
├── feature_auth
│   ├── core_network
│   │   └── core_common
│   └── core_storage
│       └── core_common
├── feature_home
│   └── core_network
│       └── core_common
└── app_debugger_impl
    └── core_common
```

--------------------------------

### Bootstrap Monorepo and Run App

Source: https://archipelago.banuacoder.com/docs/guide/getting-started.html

After creating a project, bootstrap the monorepo using Melos to link packages and run `pub get`, then start the Flutter app.

```bash
cd my_app
melos bootstrap
flutter run
```

--------------------------------

### Post-scaffolding setup

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-app-scaffold.html

Required steps to resolve dependencies, generate code, and configure flavors after scaffolding.

```bash
# 1. Resolve workspace dependencies
dart pub get

# 2. Generate injectable, auto_route, and other code
melos run build

# 3. Generate platform directories (Android/iOS)
flutter create apps/my_app --org com.example

# 4. Apply flavor configuration
melos run flavor:generate -- --app my_app
```

--------------------------------

### Configuration File Example (flavors.yaml)

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-run-app.html

This YAML file configures your apps, their IDs, and available flavors. Ensure this file is at the root of your workspace.

```yaml
apps:
  template_app:
    android_app_id: com.example.template_app
    ios_bundle_id: com.example.templateApp
    flavors:
      - development
      - staging
      - production
```

--------------------------------

### UI Kit Manager - `status` Subcommand

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Shows which components are currently installed and how many are available.

```APIDOC
## `ui-kit status`

### Description
Shows which components are currently installed and how many are available. Output includes both built-in installed components and custom components.

### Usage
```bash
dart run monorepo_toolkit ui-kit status
```
```

--------------------------------

### Interactive Prompt Example

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-run-app.html

This is an example of the interactive prompts you will see when running the app command. It shows the selection of app, flavor, and device.

```text
📱 Available apps:
  1. template_app

Select app [1]: 1

🎨 Available flavors:
  1. development
  2. staging
  3. production

Select flavor [1]: 1

📲 Connected devices:
  1. iPhone 15 Pro (ios) - 1A2B3C4D
  2. Pixel 7 (android) - emulator-5554

Select device [1]: 2

🚀 Running: flutter run --flavor development --target lib/main_development.dart -d emulator-5554
```

--------------------------------

### UI Kit Manager - `add` Subcommand

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Installs a component and its dependencies into your UI Kit.

```APIDOC
## `ui-kit add`

### Description
Installs a component and its dependencies into your UI Kit. Dependencies are resolved automatically.

### Usage
```bash
dart run monorepo_toolkit ui-kit add app-button
dart run monorepo_toolkit ui-kit add app-button --ui-kit-path packages/my_ui_kit
```

### Parameters

#### Query Parameters

- **`--ui-kit-path`** (`string`) - Optional - Default: `packages/app_ui_kit` - Path to the UI Kit package.
```

--------------------------------

### Install Mason brick

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-app-scaffold.html

Commands to install the app_scaffold Mason brick for enhanced scaffolding capabilities.

```bash
# From mason.yaml (if configured in the workspace)
mason add app_scaffold

# From a git repository
mason add app_scaffold --git-url https://github.com/banua-coder/archipelago

# Globally
mason add -g app_scaffold
```

--------------------------------

### Generate Introduction SDK (Interactive)

Source: https://archipelago.banuacoder.com/docs/bricks/introduction-sdk.html

Use this command for interactive generation of the introduction SDK feature. Ensure Archipelago CLI is installed.

```bash
archipelago generate introduction_sdk
```

--------------------------------

### CI Integration Example

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-coverage.html

Snippet for running the full coverage pipeline within a CI workflow step.

```yaml
steps:
  - name: Run coverage pipeline
    run: dart run monorepo_toolkit coverage full -j 4
```

--------------------------------

### Generate Introduction SDK (Config File)

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-introduction-sdk.html

Generate the Introduction SDK using a JSON configuration file for non-interactive setup. Ensure appName matches your monorepo app name.

```json
{
  "appName": "MyApp",
  "isForMonorepo": true
}
```

```bash
archipelago generate introduction_sdk --config intro_config.json
```

--------------------------------

### Add a UI Kit Component

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Install a component into your UI Kit. Dependencies are automatically resolved and installed. Specify a custom path to the UI Kit if it's not in the default location.

```bash
dart run monorepo_toolkit ui-kit add app-button
```

```bash
dart run monorepo_toolkit ui-kit add app-button --ui-kit-path packages/my_ui_kit
```

--------------------------------

### Install and Verify Archipelago CLI

Source: https://archipelago.banuacoder.com/docs/guide/cli-reference.html

Commands to install the CLI globally via Dart and verify the installation version.

```bash
dart pub global activate archipelago_cli
```

```bash
archipelago --version
```

--------------------------------

### Integrate with CI/CD

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-build-prepare.html

Example GitHub Actions workflow steps for managing dependencies during build.

```yaml
steps:
  - name: Prepare release deps
    run: dart run monorepo_toolkit build-prepare release

  - name: Build release
    run: flutter build appbundle --flavor production

  - name: Restore debug deps
    run: dart run monorepo_toolkit build-prepare debug
```

--------------------------------

### Show Installed UI Kit Components

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Display the status of installed components, including both built-in and custom components. This command helps you see what is currently part of your UI Kit.

```bash
dart run monorepo_toolkit ui-kit status
```

--------------------------------

### View pubspec.yaml dependency states

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-build-prepare.html

Examples of how dependencies appear in pubspec.yaml after running build-prepare.

```yaml
dependencies:
  monitoring_impl:
    path: ../../infrastructure/monitoring_impl
```

```yaml
dependencies:
  monitoring_noop:
    path: ../../infrastructure/monitoring_noop
```

--------------------------------

### Register Utilities SDK

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-utilities-sdk.html

Initialize the SDK within the dependency injection setup.

```dart
import 'package:utilities_sdk/utilities_sdk.dart';

// Register in your DI setup
UtilitiesSdk.register();
```

--------------------------------

### Navigate and Get Dependencies for the Monorepo

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-flutter-modular-monorepo.html

After generating the monorepo, navigate into the project directory and run `dart pub get` to fetch all necessary Dart dependencies. Then, navigate into the app directory to prepare for running the Flutter application.

```bash
cd tokopay
dart pub get
cd apps/tokopay
```

--------------------------------

### Theme Variant YAML Configuration Example

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Example configuration file for generating theme variants. Each entry in the 'variants' list defines a new theme, which will result in a separate Dart file.

```yaml
variants:
  - name: ocean
  - name: sunset
  - name: forest
```

--------------------------------

### Activate Monorepo Toolkit Locally

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-monorepo-toolkit.html

Navigate to the generated toolkit directory and run 'dart pub get' followed by the help command to verify activation.

```bash
cd devtools/monorepo_toolkit
dart pub get
dart run bin/monorepo_toolkit.dart --help
```

--------------------------------

### Coverage Configuration Schema

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-coverage.html

Example of a coverage.yaml file defining global thresholds, exclusions, and package-specific overrides.

```yaml
global:
  min_line_threshold: 80
  min_branch_threshold: 70
  min_function_threshold: 80

  exclude_patterns:
    - "*.g.dart"
    - "*.freezed.dart"
    - "*.config.dart"
    - "*.module.dart"
    - "*.gr.dart"
    - "**/generated/**"

  exclude_files:
    - "lib/main.dart"
    - "lib/bootstrap.dart"
    - "**/injector.dart"
    - "**/register_module.dart"

packages:
  auth_impl:
    min_line_threshold: 90
  monitoring_noop:
    skip: true
```

--------------------------------

### CLI: workspace setup

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-workspace-setup.html

Migrates the root pubspec.yaml workspace list from explicit paths to glob patterns and ensures resolution fields are correctly set.

```APIDOC
## workspace setup

### Description
Migrates the root pubspec.yaml workspace list from an explicit path list to glob patterns, then fixes resolution: workspace on all matched packages.

### Parameters
#### Flags
- **--dry-run / -n** (flag) - Optional - Show what would be done without making changes
- **--fix-resolution / -r** (flag) - Optional - Add resolution: workspace to packages missing it (default: on)

### Request Example
`dart run monorepo_toolkit workspace setup --dry-run`
```

--------------------------------

### CI Pipeline Integration

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-dependency-graph.html

Example configuration for running validation and cycle checks in a CI environment.

```yaml
- name: Validate dependency graph
  run: dart run monorepo_toolkit graph validate

- name: Check for cycles
  run: dart run monorepo_toolkit graph cycles
```

--------------------------------

### Migrate to Glob Patterns and Fix Resolution

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-workspace-setup.html

Use the `workspace setup` command to migrate from explicit package lists to glob patterns and automatically add `resolution: workspace` to packages.

```bash
# Migrate to glob patterns and fix resolution fields
dart run monorepo_toolkit workspace setup

# Preview changes without modifying files
dart run monorepo_toolkit workspace setup --dry-run

# Skip adding resolution: workspace to packages
dart run monorepo_toolkit workspace setup --no-fix-resolution
```

--------------------------------

### Generate Monorepo Toolkit with Config File

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-monorepo-toolkit.html

Alternatively, generate the monorepo toolkit using a configuration file for non-interactive setup.

```json
{
  "appName": "MyApp",
  "organization": "MyCompany",
  "isForMonorepo": true
}
```

```bash
archipelago generate monorepo_toolkit --config toolkit_config.json
```

--------------------------------

### Generate Core Infrastructure Package (Interactive)

Source: https://archipelago.banuacoder.com/docs/bricks/core-infrastructure-package.html

Use this command for interactive generation of the core infrastructure package. Ensure the Archipelago CLI is installed.

```bash
archipelago generate core_infrastructure_package
```

--------------------------------

### Introduction SDK Usage

Source: https://archipelago.banuacoder.com/docs/bricks/introduction-sdk.html

Instructions on how to generate the Introduction SDK, both interactively and non-interactively.

```APIDOC
## Introduction SDK Usage

### Description
How to generate the Introduction SDK feature.

### Interactive Usage
Use the following command for interactive generation:
```bash
archipelago generate introduction_sdk
```

### Non-interactive (CI) Usage
Use the following command for non-interactive generation, typically in a CI environment:
```bash
archipelago generate introduction_sdk --config my_config.json
```
```

--------------------------------

### Generate Initializer Skeleton (Config File)

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-initializer-skeleton.html

Generate an initializer using a JSON configuration file for non-interactive setup. This is useful for scripting or automated processes.

```json
{
  "appName": "MyApp",
  "initializerType": "pre_launch",
  "initializerName": "Analytics"
}
```

```bash
archipelago generate initializer_skeleton --config init_config.json
```

--------------------------------

### Optimize Assets with Default Settings

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-asset-optimizer.html

Run this command to optimize all image assets using the tool's default configuration and paths. Ensure you have the monorepo_toolkit installed.

```bash
dart run monorepo_toolkit assets optimize
```

--------------------------------

### Generate Introduction SDK (Non-interactive CI)

Source: https://archipelago.banuacoder.com/docs/bricks/introduction-sdk.html

Use this command for non-interactive generation, suitable for CI environments. Specify a configuration file for settings.

```bash
archipelago generate introduction_sdk --config my_config.json
```

--------------------------------

### UI Kit Manager - `create` Subcommand

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Scaffolds a new custom component with a starter widget file and registers it in the component registry.

```APIDOC
## `ui-kit create`

### Description
Scaffolds a new custom component with a starter widget file and registers it in the component registry. The generated file is placed at `lib/src/components/<layer>/<name>/app_<name>.dart`.

### Usage
```bash
dart run monorepo_toolkit ui-kit create --name status-badge --layer atom
dart run monorepo_toolkit ui-kit create --name login-form --layer organism -d app-button -d app-input
```

### Parameters

#### Query Parameters

- **`--name`** (`string`) - Required - Component name in kebab-case.
- **`-n`** (`string`) - Required - Abbreviation for `--name`.
- **`--layer`** (`atom`, `molecule`, `organism`, `template`, `page`) - Optional - Default: `atom` - Atomic design layer.
- **`-l`** (`atom`, `molecule`, `organism`, `template`, `page`) - Optional - Abbreviation for `--layer`.
- **`--dependency`** (`string`) - Optional - Component dependencies (repeatable).
- **`-d`** (`string`) - Optional - Abbreviation for `--dependency`.
- **`--ui-kit-path`** (`string`) - Optional - Default: `packages/app_ui_kit` - Path to the UI Kit package.
```

--------------------------------

### Wire Up Dependencies in DI Module

Source: https://archipelago.banuacoder.com/docs/tutorials/getting-started-generating-features.html

If your generated feature depends on other SDKs, the DI module handles wiring them up. This example shows how to register datasources, repositories, and usecases, potentially using a NetworkSDK.

```dart
// payments_impl/lib/src/di/payments_module.dart
class PaymentsModule {
  static void register() {
    final networkSdk = GetIt.I<NetworkSDK>();
    // Register datasources, repos, usecases...
  }
}
```

--------------------------------

### Install Patrol CLI

Source: https://archipelago.banuacoder.com/docs/guide/testing.html

Install the Patrol CLI globally using Dart's package manager.

```bash
dart pub global activate patrol_cli
```

--------------------------------

### Verify Archipelago CLI Installation

Source: https://archipelago.banuacoder.com/docs/guide/getting-started.html

Check if the Archipelago CLI has been installed correctly by running the version command.

```bash
archipelago --version
```

--------------------------------

### Generate Home SDK (CLI with Config)

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-home-sdk.html

Generate the Home SDK by specifying a configuration file path in the CLI command.

```bash
archipelago generate home_sdk --config home_config.json
```

--------------------------------

### Run build-prepare commands

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-build-prepare.html

Commands to toggle between debug and release dependency configurations.

```bash
# Swap to debug dependencies for development
dart run monorepo_toolkit build-prepare debug

# Swap to release (noop) dependencies for production builds
dart run monorepo_toolkit build-prepare release

# Use a custom config path
dart run monorepo_toolkit build-prepare release --config path/to/config.yaml
```

--------------------------------

### Manage app flavors

Source: https://archipelago.banuacoder.com/docs/guide/monorepo-toolkit.html

Commands for listing, adding, generating, and syncing app flavors.

```bash
melos run flavor:list-apps
```

```bash
melos run flavor:list
```

```bash
melos run flavor:add
```

```bash
melos run flavor:generate
```

```bash
melos run flavor:sync
```

--------------------------------

### Locking the RouteRegistry

Source: https://archipelago.banuacoder.com/docs/tutorials/architecture-feature-sdk-registration.html

Prevents further route registration after the initial setup phase.

```dart
routeRegistry.lock();
```

--------------------------------

### UI Kit Manager - `remove` Subcommand

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Removes a component from the installed registry.

```APIDOC
## `ui-kit remove`

### Description
Removes a component from the installed registry.

### Usage
```bash
dart run monorepo_toolkit ui-kit remove app-button
```

### Parameters

#### Query Parameters

- **`--ui-kit-path`** (`string`) - Optional - Default: `packages/app_ui_kit` - Path to the UI Kit package.
```

--------------------------------

### Run Application by Flavor

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-app-scaffold.html

Commands to execute the application using specific entry points for different environments.

```bash
flutter run --target lib/main_development.dart
flutter run --target lib/main_staging.dart
flutter run --target lib/main_production.dart
```

--------------------------------

### Scaffold a new project

Source: https://archipelago.banuacoder.com/docs/tutorials/getting-started-first-project.html

Use the create command to initialize a new monorepo structure.

```bash
archipelago create my_app
```

--------------------------------

### GET brick info

Source: https://archipelago.banuacoder.com/docs/guide/cli-reference.html

Retrieves detailed information about a specific brick template.

```APIDOC
## GET brick info

### Description
Displays detailed information about a specific brick, including category, description, tier, size, and dependencies.

### Method
GET

### Endpoint
archipelago brick info <name>

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the brick to inspect.
```

--------------------------------

### Run Build Prepare for Release

Source: https://archipelago.banuacoder.com/docs/guide/architecture.html

Execute the `build-prepare:release` command before building for production to swap debug dependencies with their release counterparts.

```bash
# Before building for production
melos run build-prepare:release
flutter build appbundle --release
```

--------------------------------

### Define Feature-Scoped Translations

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-flutter-l10n.html

Example of adding a nested namespace for modular feature translations.

```json
// Feature-scoped keys
{
  "payment": {
    "checkout": "Proceed to Checkout",
    "total": "Total: {amount}"
  }
}
```

--------------------------------

### Create a Custom UI Kit Component

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Scaffold a new custom component with starter files and register it. You can specify dependencies and the atomic design layer. The component will be placed in the standard directory structure.

```bash
dart run monorepo_toolkit ui-kit create --name status-badge --layer atom
```

```bash
dart run monorepo_toolkit ui-kit create --name login-form --layer organism -d app-button -d app-input
```

--------------------------------

### Use Melos shortcuts

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-build-prepare.html

Convenience scripts for running build-prepare via Melos.

```bash
melos run build-prepare:debug    # Swap to debug dependencies
melos run build-prepare:release  # Swap to release (noop) dependencies
```

--------------------------------

### Introduction SDK Generated Structure

Source: https://archipelago.banuacoder.com/docs/bricks/introduction-sdk.html

Illustrates the file and directory structure generated by the Introduction SDK.

```APIDOC
## Introduction SDK Generated Structure

### Description
Shows the typical file and directory structure created after generating the Introduction SDK.

### Structure
```
features/
└── introduction/
    ├── README.md
    ├── lib/
    │   ├── introduction.dart
    │   └── src/
    │       ├── introduction_sdk.dart          # FeatureSDK implementation
    │       ├── di/
    │       │   └── introduction_global_module.dart
    │       ├── presentation/
    │       │   ├── introduction_shell_page.dart
    │       │   ├── welcome_page.dart
    │       │   ├── features_page.dart
    │       │   └── get_started_page.dart
    │       └── router/
    │           ├── introduction_router.dart
    │           └── introduction_router.gr.dart
    └── pubspec.yaml
```
```

--------------------------------

### Activate Archipelago CLI

Source: https://archipelago.banuacoder.com/docs/blog/flutter-monorepo-architecture.html

Installs the Archipelago CLI globally via the Dart package manager.

```bash
dart pub global activate archipelago_cli
```

--------------------------------

### Consume Network Client in Datasources

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-network-sdk.html

Example of using the NetworkClient within a feature-specific remote datasource.

```dart
// In a feature's remote datasource
class PaymentRemoteDatasource {
  final NetworkClient _client;

  PaymentRemoteDatasource(this._client);

  Future<List<PaymentModel>> getPayments() async {
    final response = await _client.get('/payments');
    return (response.data as List)
        .map((e) => PaymentModel.fromJson(e))
        .toList();
  }

  Future<PaymentModel> createPayment(CreatePaymentRequest request) async {
    final response = await _client.post(
      '/payments',
      body: request.toJson(),
    );
    return PaymentModel.fromJson(response.data);
  }
}
```

--------------------------------

### Manage project configuration

Source: https://archipelago.banuacoder.com/docs/guide/monorepo-toolkit.html

Lists configuration values or publishes them across the workspace.

```bash
melos run config:list
```

```bash
melos run config:publish
```

--------------------------------

### Asset Generator Pro - Generated Structure

Source: https://archipelago.banuacoder.com/docs/bricks/asset-generator.html

An example of the directory structure generated by the asset_generator tool.

```APIDOC
## Asset Generator Pro - Generated Structure

This is an example of the file and directory structure that the asset generator might produce.

```
devtools/
└── scripts/
    └── asset_generator/
        ├── lib/
        │   ├── asset_generator.dart
        │   └── src/
        │       ├── asset_gen_command.dart
        │       ├── commands/
        │       │   ├── asset_gen_command.dart
        │       │   └── generate_command.dart
        │       ├── models/
        │       │   ├── asset_generator_config.dart
        │       │   └── discovered_asset.dart
        │       └── services/
        │           └── asset_scanner_service.dart
        └── pubspec.yaml
```
```

--------------------------------

### Implement Custom Lint Rule

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-app-lints.html

Example of a custom lint rule class for enforcing architecture conventions.

```dart
// lib/src/rules/feature_import_rule.dart
// Prevents features from importing other feature implementations directly
// Features should only depend on _api packages, never _impl
class FeatureImportRule extends LintRule {
  @override
  void check(Source source) {
    // Flag imports like: import 'package:auth_sdk_impl/...'
    // from within another feature's code
  }
}
```

--------------------------------

### Configure build_prepare.yaml

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-build-prepare.html

Define dependency mappings and target paths for the build-prepare tool.

```yaml
build_prepare:
  mappings:
    - debug: monitoring_impl
      release: monitoring_noop

    - debug: app_debugger
      release: app_debugger_noop

  target_paths:
    - apps/template_app
```

--------------------------------

### List apps with flavor configurations

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-flavor-manager.html

Lists all apps in the workspace that have flavor configurations defined.

```bash
dart run monorepo_toolkit flavor list-apps
```

--------------------------------

### Generate state management interactively

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-state-management.html

Run these commands from the monorepo root to start the interactive generation process.

```bash
mason make state_management --stateManagement cubit --featureName auth
```

```bash
archipelago generate state_management
```

--------------------------------

### Implement No-op Monitoring Client

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-monitoring-sdk.html

Example of a no-op implementation that satisfies the MonitoringClient interface without performing any actions.

```dart
// monitoring_sdk_noop/lib/src/noop_monitoring_client.dart
class NoopMonitoringClient implements MonitoringClient {
  @override
  Future<void> init() async {}

  @override
  void captureException(Object error, {StackTrace? stackTrace}) {}

  @override
  void startPerformanceTrace(String name) {}

  @override
  void stopPerformanceTrace(String name) {}
}
```

--------------------------------

### Generate flutter_ui_kit Interactively

Source: https://archipelago.banuacoder.com/docs/bricks/flutter-ui-kit.html

Use this command to generate the flutter_ui_kit with interactive prompts for configuration. Ensure Archipelago CLI is installed.

```bash
archipelago generate flutter_ui_kit
```

--------------------------------

### List All UI Kit Components

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Use this command to see all available components in the design system library, grouped by their atomic design layer.

```bash
dart run monorepo_toolkit ui-kit list
```

--------------------------------

### Generate Coverage Manager Command

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-coverage-manager.html

Use the CLI to generate the coverage manager or provide a configuration file for automated setup.

```bash
archipelago generate coverage_manager
```

```json
{
  "appName": "MyApp",
  "isForMonorepo": true
}
```

```bash
archipelago generate coverage_manager --config coverage_config.json
```

--------------------------------

### Generate Shared Utilities Package (Config)

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-app-utilities.html

Alternatively, generate the app_utilities package using a configuration file for non-interactive setup.

```json
{
  "appName": "MyApp",
  "isForMonorepo": true
}
```

--------------------------------

### Generate Paywall SDK (Interactive)

Source: https://archipelago.banuacoder.com/docs/bricks/paywall-sdk.html

Use this command to interactively generate the paywall SDK. It prompts for necessary configuration details.

```bash
archipelago generate paywall_sdk
```

--------------------------------

### HostAppWidget Initialization Flow

Source: https://archipelago.banuacoder.com/docs/tutorials/architecture-two-phase-init.html

Visual representation of the HostAppWidget lifecycle, detailing the sequence of pre-launch and post-launch initialization steps.

```text
HostAppWidget.initState()
  |-- PreLaunchInitializerController.initialize()
  |     |-- Sequential initializers (in order)
  |     |-- Parallel initializers (concurrent)
  |     |-- FeatureSDK route registration
  |     |-- RouteRegistry.lock()
  |     |-- FeatureSDK initialization
  |     \-- Return InitializerResult with AppRouter
  |
  |-- Completer.complete(result) --> FutureBuilder rebuilds
  |     \-- AnimatedSwitcher: loading -> app (FadeTransition)
  |
  \-- addPostFrameCallback()
        |-- benchmark.markFirstFrameRendered()
        \-- PostLaunchInitializer.create().initialize()
              |-- Sequential initializers
              |-- Parallel initializers
              \-- benchmark.printSummary()
```

--------------------------------

### Run Widgetbook Showcase App

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-flutter-ui-kit.html

Navigate to the Widgetbook package directory and run `flutter run` to launch the showcase application, which displays all generated UI components.

```bash
cd packages/tokopay_ui_kit_widgetbook
flutter run -d chrome
```

--------------------------------

### Customize Dashboard Page

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-home-sdk.html

Modify the generated dashboard page by adding your custom widgets. This example shows how to structure the Scaffold body.

```dart
// home_sdk/lib/src/presentation/ui/pages/dashboard_page.dart
class DashboardPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          // Add your dashboard widgets here
          const WelcomeHeader(),
          const QuickActions(),
          const RecentActivity(),
        ],
      ),
    );
  }
}
```

--------------------------------

### Basic Patrol Test Example

Source: https://archipelago.banuacoder.com/docs/guide/testing.html

A simple Patrol test case that verifies the app launches successfully and interacts with native permissions.

```dart
import 'package:patrol/patrol.dart';

import 'patrol_config.dart';

void main() {
  patrolTest(
    'app launches successfully',
    config: patrolTestConfig,
    ($) async {
      // Verify the app renders
      expect($('Archipelago'), findsOneWidget);

      // Interact with native elements
      await $.native.grantPermissionWhenInUse();
    },
  );
}
```

--------------------------------

### Generate Utilities SDK

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-utilities-sdk.html

Use the CLI command or a JSON configuration file to generate the SDK with specific modules enabled.

```bash
archipelago generate utilities_sdk
```

```json
{
  "appName": "MyApp",
  "organization": "MyCompany",
  "domain": "com",
  "prefix": "App",
  "includeDeviceInfo": true,
  "includePackageInfo": true,
  "includeBiometric": true,
  "isForMonorepo": true,
  "includeGenerated": false
}
```

--------------------------------

### UI Kit Manager - `list` Subcommand

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-ui-kit.html

Lists all available components from the built-in registry, optionally filtered by atomic design layer.

```APIDOC
## `ui-kit list`

### Description
Lists all available components from the built-in registry, grouped by atomic design layer.

### Usage
```bash
dart run monorepo_toolkit ui-kit list
dart run monorepo_toolkit ui-kit list --layer organism
```

### Parameters

#### Query Parameters

- **`--layer`** (`atom`, `molecule`, `organism`, `template`, `page`) - Optional - Filter by atomic design layer.
- **`-l`** (`atom`, `molecule`, `organism`, `template`, `page`) - Optional - Abbreviation for `--layer`.
```

--------------------------------

### Initialize Environment Configuration

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-env-sync.html

Initializes the environment configuration structure, creating per-flavor envied classes, .env template files, and the main Env class. Defaults to API_BASE_URL and AES_KEY.

```bash
dart run monorepo_toolkit env init
```

```bash
# Specify initial variables (defaults to API_BASE_URL and AES_KEY)
dart run monorepo_toolkit env init --var API_BASE_URL --var AES_KEY --var SECRET
```

--------------------------------

### CI Integration for Affected Packages

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-affected.html

Example CI steps to analyze and test affected packages. It specifies the base branch for comparison.

```yaml
steps:
  - name: Analyze affected packages
    run: dart run monorepo_toolkit affected analyze --base origin/develop

  - name: Test affected packages
    run: dart run monorepo_toolkit affected test --coverage --base origin/develop
```

--------------------------------

### Generate Size Guard Command

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-size-guard.html

Use the CLI to generate the size guard command or provide a configuration file for automated setup.

```bash
archipelago generate size_guard
```

```json
{
  "appName": "MyApp",
  "isForMonorepo": true
}
```

```bash
archipelago generate size_guard --config size_guard_config.json
```

--------------------------------

### Initialize Coverage Configuration

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-coverage.html

Creates a default coverage.yaml file at the workspace root.

```bash
dart run monorepo_toolkit coverage init
```

--------------------------------

### Manage app targets

Source: https://archipelago.banuacoder.com/docs/guide/monorepo-toolkit.html

Scaffolds a new app target in the apps directory.

```bash
melos run app:create
```

--------------------------------

### Generate App Lints Interactively

Source: https://archipelago.banuacoder.com/docs/bricks/app-lints.html

Use this command to interactively generate the app_lints package. This is suitable for local development and initial setup.

```bash
archipelago generate app_lints
```

--------------------------------

### Activate Monorepo Toolkit Globally

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-monorepo-toolkit.html

Activate the toolkit globally for convenient access from any directory. Use 'monorepo_toolkit --help' to see available commands.

```bash
dart pub global activate --source path devtools/monorepo_toolkit
monorepo_toolkit --help
```

--------------------------------

### Implement GetUserUseCase using BaseUseCase

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-core-infrastructure-package.html

Example of a UseCase extending BaseUseCase, demonstrating dependency injection of a UserRepository and executing a user retrieval operation.

```dart
class GetUserUseCase extends BaseUseCase<String, User> {
  final UserRepository _repository;

  GetUserUseCase(this._repository);

  @override
  Future<Result<User>> execute(String userId) {
    return _repository.getUser(userId);
  }
}
```

--------------------------------

### Basic Initializer Structure

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-initializer-skeleton.html

The generated initializer file extends the `Initializer` base class and requires implementing the `initialize` method for your setup logic.

```dart
class AnalyticsInitializer extends Initializer {
  @override
  Future<void> initialize() async {
    // Your initialization logic here
  }
}
```

--------------------------------

### Run Integration Tests with Flutter Driver

Source: https://archipelago.banuacoder.com/docs/guide/testing.html

For CI environments that do not have Patrol installed, use the standard Flutter integration test driver to run tests.

```bash
flutter test integration_test/app_test.dart
```

--------------------------------

### Environment Configuration

Source: https://archipelago.banuacoder.com/docs/guide/monorepo-toolkit.html

Commands to initialize and manage environment variables.

```bash
melos run env:init
```

```bash
melos run env:add
```

--------------------------------

### Example of Generated Envied Class

Source: https://archipelago.banuacoder.com/docs/guide/toolkit-env-sync.html

Illustrates a generated envied class providing compile-time access to environment variables, using @Envied and @EnviedField annotations.

```dart
@Envied(path: '.env.development')
abstract class DevelopmentEnv {
  @EnviedField(varName: 'API_BASE_URL')
  static const String apiBaseUrl = _DevelopmentEnv.apiBaseUrl;
}
```

--------------------------------

### Generate app scaffold

Source: https://archipelago.banuacoder.com/docs/bricks/app-scaffold.html

Use these commands to initialize a new application structure within an existing Archipelago workspace.

```bash
archipelago generate app_scaffold
```

```bash
archipelago generate app_scaffold --config my_config.json
```

--------------------------------

### Initialize Global GetIt Instance

Source: https://archipelago.banuacoder.com/docs/tutorials/architecture-dual-getit.html

Sets up the global GetIt instance and initializes it with external package modules and feature SDKs. External modules are registered before feature SDKs.

```dart
final getIt = GetIt.instance;

@InjectableInit(
  externalPackageModulesBefore: [
    ExternalModule(AppUtilitiesPackageModule),
    ExternalModule(NetworkSdkDioPackageModule),
    ExternalModule(MonitoringImplPackageModule),
    ExternalModule(RouterRegistryPackageModule),
    // Feature SDKs (eager — triggers self-registration)
    ExternalModule(AuthImplGlobalModule),
    ExternalModule(HomeImplGlobalModule),
  ],
)
Future<void> initializeInjector() => $initGetIt(getIt);
```

--------------------------------

### Generate Core Infrastructure Package

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-core-infrastructure-package.html

Use this command to generate the core infrastructure package. You can provide parameters directly or use a configuration file.

```bash
archipelago generate core_infrastructure_package
```

```json
{
  "appName": "MyApp",
  "organization": "MyCompany",
  "domain": "com",
  "prefix": "App",
  "isForMonorepo": true,
  "includeGenerated": false
}
```

```bash
archipelago generate core_infrastructure_package --config core_config.json
```

--------------------------------

### Manage UI kit components

Source: https://archipelago.banuacoder.com/docs/guide/monorepo-toolkit.html

Commands to list, add, remove, check status, or create new UI kit packages.

```bash
melos run ui-kit:list
```

```bash
melos run ui-kit:add
```

```bash
melos run ui-kit:remove
```

```bash
melos run ui-kit:status
```

```bash
melos run ui-kit:create
```

--------------------------------

### Customize High Contrast Typography

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-ui-kit-theme.html

Customize typography styles in `high_contrast_typography.dart` for better readability. This example makes the `bodyLarge` text bolder and adjusts letter spacing.

```dart
// high_contrast_typography.dart
class HighContrastTypography extends AppTypography {
  @override
  TextStyle get bodyLarge => super.bodyLarge.copyWith(
    fontWeight: FontWeight.w600,  // Bolder text for readability
    letterSpacing: 0.5,
  );
}
```

--------------------------------

### Configure build_prepare Flavors

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-monitoring-sdk.html

Configuration for mapping build flavors to specific monitoring SDK implementations and the command to apply these changes.

```yaml
# build_prepare.yaml
flavors:
  development:
    monitoring_sdk:
      dependency: monitoring_sdk_noop    # No-op in dev
  staging:
    monitoring_sdk:
      dependency: monitoring_sdk_noop    # No-op in staging
  production:
    monitoring_sdk:
      dependency: monitoring_sdk_impl    # Real in production
```

```bash
dart run devtools/build_prepare.dart --flavor production
```

--------------------------------

### Introduction SDK Variables

Source: https://archipelago.banuacoder.com/docs/bricks/introduction-sdk.html

Defines the variables available for configuring the Introduction SDK.

```APIDOC
## Introduction SDK Variables

### Description
Variables that can be configured for the Introduction SDK.

### Variables
- **appName** (string) - Optional - The name of your application. Defaults to 'MyApp'.
- **isForMonorepo** (boolean) - Optional - Whether this will be part of a monorepo structure. Defaults to 'true'.
```

--------------------------------

### Example pubspec.yaml Dependency Changes

Source: https://archipelago.banuacoder.com/docs/tutorials/deploy-build-prepare.html

Illustrates how `app/pubspec.yaml` is modified by `build_prepare` when switching between debug and release modes. The `app_debugger_impl` dependency is swapped with `app_debugger` for release builds.

```yaml
# Before (debug mode)
dependencies:
  app_debugger_impl:
    path: ../packages/app_debugger_impl

# After (release mode)
dependencies:
  app_debugger:
    path: ../packages/app_debugger
```

--------------------------------

### Run Tests on Affected Packages in CI

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-monorepo-toolkit.html

This example demonstrates how to run tests only on packages that have changed since a specific git reference, useful for CI environments.

```bash
monorepo_toolkit affected --since origin/main | xargs -I {} sh -c 'cd {} && flutter test'
```

--------------------------------

### Generate Auth SDK with Config Flag

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-auth-sdk.html

Generate the Auth SDK by specifying the configuration file path directly via a CLI flag.

```bash
archipelago generate auth_sdk --config auth_config.json
```

--------------------------------

### Run Integration Tests with Patrol

Source: https://archipelago.banuacoder.com/docs/guide/testing.html

Execute integration tests using the Patrol CLI. This example shows how to run tests for a specific flavor and target file.

```bash
cd apps/template_app
patrol test --flavor development --target integration_test/app_test.dart
```

--------------------------------

### Bootstrap Entry Point for Flutter App

Source: https://archipelago.banuacoder.com/docs/tutorials/architecture-two-phase-init.html

The main entry point for a Flutter application, handling top-level error catching and initial setup before running the app.

```dart
Future<void> bootstrap({
  required FlavorStatus flavor,
  required AppBuilder builder,
}) async => runZonedGuarded(
  () async {
    Flavor.status = flavor;

    WidgetsFlutterBinding.ensureInitialized();
    await initializeInjector();
    await SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]);

    final benchmark = StartupBenchmark(mode: flavor.name)..startApp();

    runApp(
      HostAppWidget(
        benchmark: benchmark,
        initializerController: PreLaunchInitializerController.create(),
        builder: (context, result) => builder(result, benchmark),
      ),
    );
  },
  (error, stackTrace) {
    debugPrint('Uncaught error: $error');
    debugPrint('Stack trace: $stackTrace');
  },
);
```

--------------------------------

### Generate Monitoring SDK

Source: https://archipelago.banuacoder.com/docs/tutorials/brick-monitoring-sdk.html

Commands to generate the Monitoring SDK via CLI or configuration file.

```bash
archipelago generate monitoring_sdk
```

```json
{
  "appName": "MyApp",
  "isForMonorepo": true
}
```

```bash
archipelago generate monitoring_sdk --config monitoring_config.json
```