### Post-Install Next Steps Example

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-host-app-integration-seam.md

Example of the next steps guide printed to stdout after Rulestead installation. It includes commands for database migration, server start, accessing the admin UI, adding flags, and links to relevant documentation.

```text
[rulestead] Done. Next steps:

  1. Migrate the DB:        mix ecto.migrate
  2. Start the server:      mix phx.server
  3. Visit admin UI:        http://localhost:4000/admin/flags
  4. Add your first flag:   mix rulestead.add_flag my_feature --default false

  Docs:
    - Quickstart:   https://hexdocs.pm/rulestead/introduction.html
    - Testing:      https://hexdocs.pm/rulestead/guides/testing.html
    - Policy:       https://hexdocs.pm/rulestead/guides/policy-and-change-requests.html
    - Admin tour:   https://hexdocs.pm/rulestead/guides/operator-handbook.html

  Generated files to review + commit:
    - lib/my_app/rulestead_actor_resolver.ex   (customize to match your auth)
    - lib/my_app/rulestead_admin_policy.ex     (customize authz rules)
    - priv/repo/migrations/2026...              (standard ecto migrations)
    - lib/my_app_web/router.ex                  (admin mounted at /admin/flags)
    - config/config.exs                         (rulestead config block)

```

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

### Installer Driver Example

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-host-app-integration-seam.md

Demonstrates how to use the Rulestead installer driver to iterate through a list of features, applying them conditionally based on their applicability.

```elixir
features = [
  Rulestead.Install.Features.Core,
  Rulestead.Install.Features.Admin,
  Rulestead.Install.Features.Oban,
  Rulestead.Install.Features.Telemetry,
  Rulestead.Install.Features.AuditSign
]

Enum.reduce(features, initial_state, fn feature, state ->
  if feature.applicable?(state), do: feature.apply(state), else: state
end)
```

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

### Installer Golden-Diff Test Setup

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-engineering-dna-from-prior-libs.md

Demonstrates setting up a new Phoenix project, injecting Rulestead, running the install mix task, and capturing stdout for comparison. Normalizes migration timestamps before diffing.

```Elixir
System.cmd("mix phx.new <tmp>")
```

```Elixir
{:rulestead, path: "..", override: true}
```

```Elixir
mix rulestead.install ...
```

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

### Install and Migrate Rulestead

Source: https://github.com/sztheory/rulestead/blob/main/README.md

Install Rulestead and run database migrations for your project.

```bash
mix deps.get
mix rulestead.install
mix ecto.migrate
```

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

### Feature Walker Pattern Example

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-host-app-integration-seam.md

Illustrates the feature-walker pattern used by the installer for optional features like admin, oban, telemetry, and audit signing.

```elixir
```elixir

```

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

### Rulestead Install Command Options

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-host-app-integration-seam.md

Lists the available command-line options for `mix rulestead.install`. These options allow customization of the installation process, such as skipping prompts, disabling specific features, specifying the application or repo in umbrella projects, and setting custom routes.

```bash
mix rulestead.install [options]

  --yes                  Skip prompts; accept all defaults
  --no-admin             Don't mount admin UI
  --no-oban              Don't wire Oban workers
  --no-migrations        Don't generate migrations (for custom store adapters)
  --no-policy-scaffold   Don't create RulesteadAdminPolicy stub
  --app MyApp            Specify which umbrella child (default: auto-detect)
  --repo MyApp.Repo      Specify repo (default: auto-detect first Ecto.Repo)
  --admin-route "/flags" Custom admin mount path (default: /admin/flags)
  --dry-run              Print injections without writing files
```

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

### Run Fresh-Install Journey Script

Source: https://github.com/sztheory/rulestead/blob/main/examples/demo/README.md

Executes a script to simulate a fresh installation journey without the FleetDesk UI.

```bash
scripts/demo/install_journey.sh
```

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

### Install Rulestead

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-personas-jtbd-and-onboarding.md

Command to install Rulestead, including interactive prompts for configuration. The `--yes` flag can be used to skip prompts.

```bash
mix rulestead.install
```

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

### Rulestead Migration Example

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-host-app-integration-seam.md

Example of a migration module that delegates to Rulestead's versioned migration logic.

```elixir
defmodule MyApp.Repo.Migrations.CreateRulesteadFlags do
  use Ecto.Migration
  def up, do: Rulestead.Migrations.V1.Flags.up()
  def down, do: Rulestead.Migrations.V1.Flags.down()
end
```

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

### Boot FleetDesk Adoption Lab with Docker Compose

Source: https://github.com/sztheory/rulestead/blob/main/examples/demo/README.md

Starts the Rulestead adoption lab services including backend, frontend, database, and cache. Ensure you are in the repository root.

```bash
docker compose up --build
```

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

### Start Local Postgres Service

Source: https://github.com/sztheory/rulestead/blob/main/CONTRIBUTING.md

Starts the local PostgreSQL database service using Docker Compose. This is required for development flows that depend on database interactions.

```bash
docker compose up -d postgres
```

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

### Run Install Journey Test

Source: https://github.com/sztheory/rulestead/blob/main/MAINTAINING.md

Execute the CI wrapper with the install_journey scope. This tests the fresh-install golden-diff journey but does not cover FleetDesk compose/Playwright.

```bash
RULESTEAD_TEST_SCOPE=install_journey bash scripts/ci/test.sh
```

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

### Elixir Behavior Callbacks - Minimal Example

Source: https://github.com/sztheory/rulestead/blob/main/prompts/elixir-opensource-libs-best-practices-deep-research.md

Define narrow behaviors with the minimum necessary callbacks. This example shows a concise `request` callback for a transport adapter, promoting composition with regular functions.

```elixir
@callback request(method, url, headers, body, opts) ::
  {:ok, status, headers, body} | {:error, Exception.t()}
```

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

### Install Rulestead Schema and Host Wiring

Source: https://github.com/sztheory/rulestead/blob/main/guides/recipes/ecto-conventions.md

Use this command to set up the base store schema and host-app wiring for Rulestead in your Phoenix application.

```bash
cd your_phoenix_app
mix deps.get
mix rulestead.install
mix ecto.migrate
```

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

### Publish Ruleset Command

Source: https://github.com/sztheory/rulestead/blob/main/guides/recipes/ecto-conventions.md

Authoring operations should be explicit about environment and mutation intent. This example shows how to create and publish a ruleset command.

```elixir
alias Rulestead.Store.Command

command = 
  Command.PublishRuleset.new("checkout-redesign", "prod",
    actor: %{id: "operator-123"},
    version: 3
  )

{:ok, published} = Rulestead.publish_ruleset(command)
```

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

### Mutation Confirmation Modal Example

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-admin-ux-and-operator-ia.md

Illustrates the common modal used for confirming mutations like advancing a rollout. It requires a reason and allows for scheduling the change.

```text
┌─────────────────────────────────────────┐
│ Confirm: Advance rollout                │
├─────────────────────────────────────────┤
│ Flag:     checkout_v2                   │
│ From:     25%                           │
│ To:       50%                           │
│ Affects:  ~24,800 more actors           │
│                                         │
│ Reason (required):                      │
│ [ textarea ...                       ]  │
│                                         │
│ Schedule: [Now ▾] (or: 2026-11-20 09:00)│
│                                         │
│ [Cancel]                  [Advance] (⏎) │
└─────────────────────────────────────────┘
```

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

### Run Database Migrations

Source: https://github.com/sztheory/rulestead/blob/main/guides/recipes/deployment.md

Include the generated Rulestead migrations in your normal deploy flow after running `mix rulestead.install`. The installed schema is required for authoring and snapshot publication.

```bash
mix ecto.migrate
```

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

### Minimum Viable Flow for Client Initialization and Search

Source: https://github.com/sztheory/rulestead/blob/main/prompts/elixir-opensource-libs-best-practices-deep-research.md

Demonstrates the simplest way to initialize an OpenSearch client and perform a search operation. This happy path should be immediately obvious and not require complex setup like supervisors or application configuration.

```elixir
client = OpenSearch.Client.new(base_url: "...", api_key: "...")
{:ok, resp} = OpenSearch.search(client, "products", %{query: %{match_all: %{}}})
```

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

### OpenSearch Telemetry Event Candidates

Source: https://github.com/sztheory/rulestead/blob/main/prompts/elixir-opensource-libs-best-practices-deep-research.md

Example telemetry events for an OpenSearch library, including start, stop, and exception events. These events should be documented and treated as a compatibility surface.

```elixir
[:opensearch, :request, :start]
[:opensearch, :request, :stop]
[:opensearch, :request, :exception]
```

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

### Starting Long-Lived Processes Under Supervision

Source: https://github.com/sztheory/rulestead/blob/main/prompts/elixir-best-practices-deep-research.md

Ensure new processes, especially long-lived ones, are started within supervisors. Avoid starting unsupervised long-running processes as it's an anti-pattern.

```elixir
# Library-owned persistent workers: supervised
# Ephemeral throwaway work: task or supervised task
# Avoid ad hoc spawn for durable work
```

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

### Idempotent Rulestead Install Re-run

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-host-app-integration-seam.md

Illustrates the output when `mix rulestead.install` is run on a project where Rulestead has already been installed. It shows messages indicating that files already exist or are already injected, confirming the idempotent nature of the installer.

```bash
$ mix rulestead.install
[rulestead] ...

[rulestead]  ~ already injected: lib/my_app/application.ex
[rulestead]  ~ already injected: lib/my_app_web/router.ex
[rulestead]  ~ already injected: config/config.exs
[rulestead]  ~ already exists: lib/my_app/rulestead_admin_policy.ex
[rulestead]  ~ already exists: priv/repo/migrations/20260423140000_create_rulestead_flags.exs
...

[rulestead] No changes needed. Everything up to date.
```

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

### Run Host Preview Evidence Proof via CI Wrapper

Source: https://github.com/sztheory/rulestead/blob/main/MAINTAINING.md

Execute the host preview evidence proof using the CI wrapper script. This is an alternative to the primary maintainer command and allows for specific test scope bounding.

```bash
RULESTEAD_TEST_SCOPE=host_preview_evidence bash scripts/ci/test.sh
```

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

### Default `mix rulestead.install` Execution

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-host-app-integration-seam.md

Demonstrates the output of running `mix rulestead.install` without any flags in a typical Phoenix project. It shows detection of the host app, Ecto repo, Oban, and LiveView, followed by a summary of features to be enabled and the files to be injected or created.

```bash
$ mix rulestead.install
[rulestead] Detecting host application...
[rulestead] Found Phoenix app: MyApp @ /Users/jon/projects/myapp
[rulestead] Found Ecto repo: MyApp.Repo
[rulestead] Oban detected (v2.18.1)
[rulestead] LiveView detected (v1.1.11)

[rulestead] Features to enable:
  [x] Core runtime (Plug, Context, Store)
  [x] Admin UI (mountable LiveView at /admin/flags)
  [x] Oban integration (rollout scheduler + audit compactor)
  [x] Telemetry + OTel adapter wiring
  [x] Ecto migrations (5 tables + audit trigger)

Continue? [Y/n] y

[rulestead]  * injecting lib/my_app/application.ex
[rulestead]  * injecting lib/my_app_web/router.ex
[rulestead]  * injecting config/config.exs
[rulestead]  * creating lib/my_app/rulestead_admin_policy.ex
[rulestead]  * creating lib/my_app/rulestead_actor_resolver.ex
[rulestead]  * creating priv/repo/migrations/20260423140000_create_rulestead_flags.exs
[rulestead]  * creating priv/repo/migrations/20260423140001_create_rulestead_rulesets.exs
[rulestead]  * creating priv/repo/migrations/20260423140002_create_rulestead_audiences.exs
[rulestead]  * creating priv/repo/migrations/20260423140003_create_rulestead_rollouts.exs
[rulestead]  * creating priv/repo/migrations/20260423140004_create_rulestead_events.exs

[rulestead] Done. Next steps:
  1. mix ecto.migrate
  2. mix phx.server
  3. Open http://localhost:4000/admin/flags
  4. Read: https://hexdocs.pm/rulestead/introduction.html
```

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

### Client Initialization with Runtime Configuration

Source: https://github.com/sztheory/rulestead/blob/main/prompts/elixir-opensource-libs-best-practices-deep-research.md

Prefer runtime configuration for library clients, explicitly passing options like base URL, transport, JSON encoder, and retry strategies.

```elixir
client = OpenSearch.Client.new(
  base_url: "...",
  transport: OpenSearch.Transport.Finch,
  json: Jason,
  retry: [...] 
)
```

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

### Idempotency Test for Installer

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-testing-and-e2e-strategy.md

Ensures that running the Rulestead installer multiple times has no unintended side effects. The second run should only report existing injections.

```elixir
test "installer is idempotent on re-run" do
  %{tmp_root: tmp} = setup_tmp_app!()
  {output, 0} = System.cmd("mix", ["rulestead.install", "--yes"],
                           cd: tmp, stderr_to_stdout: true,
                           env: [{"MIX_ENV", "test"}])
  # Second run should only emit "already injected" or "skipping (already exists)" lines.
  assert output =~ "already injected"
  refute output =~ "* injecting"
end
```

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

### Fetch Dependencies

Source: https://github.com/sztheory/rulestead/blob/main/open_feature_rulestead/README.md

After adding dependencies, fetch them using the mix command.

```bash
mix deps.get
```

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

### Installer Golden Diff Test

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-testing-and-e2e-strategy.md

Verifies that the installer produces byte-identical output compared to a golden fixture. This test is marked with :golden and has a 5-minute timeout.

```elixir
defmodule Rulestead.Install.GoldenDiffTest do
  use ExUnit.Case, async: false
  @moduletag :golden
  @moduletag timeout: 300_000  # 5-minute ceiling

  import Rulestead.Test.InstallFixture

  test "installer emits byte-identical tree" do
    %{tmp_root: tmp, stdout: stdout} = setup_tmp_app!(
      flags: []  # run installer with defaults
    )
    actual_tree  = normalize_tree(tmp, strip: ["deps/", "_build/", ".elixir_ls/"])
    actual_stdout = normalize_stdout(stdout)

    expected_tree_root = Path.join([__DIR__, "..", "..", "fixtures", "install_golden", "tree"])
    expected_stdout    = File.read!(Path.join([__DIR__, "..", "..", "fixtures", "install_golden", "STDOUT.txt"]))

    assert_tree_equal(expected_tree_root, actual_tree)
    assert String.trim(actual_stdout) == String.trim(expected_stdout)
  end
end
```

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

### Run Bounded Adopter Proof Script

Source: https://github.com/sztheory/rulestead/blob/main/examples/demo/README.md

Executes a script for bounded adopter proof, including smoke tests and mix verify.adopter.

```bash
scripts/demo/proof.sh
```

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

### Installer Flag Matrix Compilation Test

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-testing-and-e2e-strategy.md

Tests that the installer compiles successfully with various flag combinations. This helps verify feature isolation, ensuring that different features do not incorrectly depend on each other.

```elixir
@flag_matrix [
  {"defaults",      []},
  {"no-admin",      ["--no-admin"]},
  {"no-oban",       ["--no-oban"]},
  {"no-admin,oban", ["--no-admin", "--no-oban"]}
]

for {name, flags} <- @flag_matrix do
  test "installer compiles with flags: #{name}" do
    %{tmp_root: tmp} = setup_tmp_app!(extra_flags: unquote(flags))
    assert {_, 0} = System.cmd("mix", ["compile", "--warnings-as-errors"],
                               cd: tmp,
                               env: [{"MIX_ENV", "dev"}])
  end
end
```

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

### Run Host Preview Evidence Proof

Source: https://github.com/sztheory/rulestead/blob/main/MAINTAINING.md

Execute the primary maintainer command for host preview evidence proof. This command is used when work touches opt-in resolver wiring, sample cohort and impression summary on audience previews, redaction and fingerprint/stale rejection, governance boundary, mounted rendering, or root/package docs describing v1.9 support.

```bash
cd rulestead && mix verify.phase68
```

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

### LiveView Async Operations with start_async/3

Source: https://github.com/sztheory/rulestead/blob/main/prompts/phoenix-live-view-best-practices-deep-research.md

Use `start_async/3` when you want custom `handle_async/3` handling. Show loading/failed/result states via AsyncResult or `<.async_result>`.

```Elixir
start_async/3
```

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

### Elixir Behavior Callbacks - Extensive Example (Avoid)

Source: https://github.com/sztheory/rulestead/blob/main/prompts/elixir-opensource-libs-best-practices-deep-research.md

Avoid overly broad behaviors with numerous callbacks. This example illustrates an extensive set of callbacks that could likely be composed from a narrower behavior and regular functions.

```elixir
@callback init(...)
@callback prepare(...)
@callback encode(...)
@callback request(...)
@callback decode(...)
@callback handle_error(...)
@callback cleanup(...)
```

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

### Installer Path Gate Job

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-release-engineering-and-ci.md

This YAML configuration defines the 'installer_path_gate' job, which determines if subsequent installer-related jobs should run. It checks if the changes in a pull request affect installer files and sets an output to control execution flow.

```yaml
installer_path_gate:
  runs-on: ubuntu-24.04
  outputs:
    run: ${{ steps.check.outputs.run }}
  steps:
    - uses: actions/checkout@...
      with: { fetch-depth: 0 }
    - id: check
      run: |
        set -euo pipefail
        if [[ "${{ github.event_name }}" != "pull_request" ]]; then
          echo "run=true" >> "$GITHUB_OUTPUT"; exit 0
        fi
        BASE="${{ github.event.pull_request.base.sha }}"
        HEAD="${{ github.event.pull_request.head.sha }}"
        if git diff --name-only "$BASE...$HEAD" 
            | grep -qE '^priv/templates/rulestead\.install/|^lib/rulestead/install/|^lib/mix/tasks/rulestead\.install\.ex$'; then
          echo "run=true" >> "$GITHUB_OUTPUT"
        else
          echo "run=false" >> "$GITHUB_OUTPUT"
        fi
```

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

### Run Package-Local Proof Tests

Source: https://github.com/sztheory/rulestead/blob/main/open_feature_rulestead/README.md

Execute the package-local test suite to verify the Elixir provider contract. Run this command from the open_feature_rulestead/ directory.

```bash
mix test test/open_feature_rulestead/context_mapper_test.exs \
  test/open_feature_rulestead/provider_test.exs
```

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

### Enable Feature Flag Globally (FunWithFlags)

Source: https://github.com/sztheory/rulestead/blob/main/guides/recipes/migrating-from-funwithflags.md

Example of imperatively enabling a feature flag globally in FunWithFlags.

```elixir
FunWithFlags.enable(:my_feature)
```

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

### Evaluate Feature Flag Globally (FunWithFlags)

Source: https://github.com/sztheory/rulestead/blob/main/guides/recipes/migrating-from-funwithflags.md

Example of checking if a feature flag is enabled globally in FunWithFlags.

```elixir
FunWithFlags.enabled?(:my_feature)
```

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

### Run Post-GA Band Closure Proof via CI Wrapper

Source: https://github.com/sztheory/rulestead/blob/main/MAINTAINING.md

Execute the post-GA band closure proof using the CI wrapper script. This command allows for specific test scope bounding.

```bash
RULESTEAD_TEST_SCOPE=post_ga_band_closure bash scripts/ci/test.sh
```

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

### Get a flag variant

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-personas-jtbd-and-onboarding.md

Retrieves a specific variant of a flag, allowing for A/B testing or phased rollouts.

```elixir
Rulestead.get_variant(flag_payload, context, opts \\ [])
```

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

### LiveView Navigation with Patch and Navigate

Source: https://github.com/sztheory/rulestead/blob/main/prompts/phoenix-live-view-best-practices-deep-research.md

Use `<.link patch={...}>` for same-LiveView state changes to preserve scroll and apply minimal diffs. Use `<.link navigate={...}>` for moving between LiveViews to dismount the current and mount the next.

```Elixir
<.link patch={...}>
<.link navigate={...}>
```

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

### Choosing Between Supervisor and DynamicSupervisor

Source: https://github.com/sztheory/rulestead/blob/main/prompts/elixir-best-practices-deep-research.md

Use the regular Supervisor for mostly static children and DynamicSupervisor for on-demand, potentially numerous children. Avoid over-supervising by keeping the tree shallow unless a clear lifecycle reason exists.

```elixir
# Official docs say regular Supervisor is for mostly static children; DynamicSupervisor is the specialized tool for on-demand children.
#
# Don’t over-supervise
#
# Not every helper needs its own process or subtree. Keep the tree shallow until there is a clear lifecycle reason.
```

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

### Evaluate flag in controller

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-personas-jtbd-and-onboarding.md

Example of using Rulestead.Runtime.enabled? within a controller to gate a feature based on the provided context.

```elixir
Rulestead.Runtime.enabled?("dev", "checkout_v2", context)
```