Rulestead

https://github.com/sztheory/rulestead
Admin
Typed feature flags, variants, and remote config for Elixir apps with deterministic evaluation,...
Tokens:122,255
Snippets:1,578
Trust Score:9
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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.
```

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

### 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: %{}}})
```

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

### 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()}
```

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

### 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]
```

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

### 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
```

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

### 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
```

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

### 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] (⏎) │
└─────────────────────────────────────────┘
```

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

### 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
```

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

### 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 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
```

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

### Setup Rulestead OpenTelemetry Integration

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-telemetry-observability-and-audit.md

Initializes the Rulestead OpenTelemetry wrapper, enabling the conversion of Rulestead's telemetry events into OpenTelemetry spans and metrics. This is an optional dependency.

```elixir
Rulestead.OTel.setup()
```

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

### 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(...)
```

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

### 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
```

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

### Using DynamicSupervisor for Dynamic Children

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

Employ DynamicSupervisor when child processes are started on demand and can be numerous. It is optimized for dynamic children and can handle a large quantity.

```elixir
# Use when children are started on demand and numerous; docs note it is optimized for dynamic children and can handle very large numbers.
```

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

### Run End-to-End Browser Tests with Playwright

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

Installs frontend dependencies and runs Playwright end-to-end tests for the adoption lab. Ensure the backend and frontend URLs are correctly set.

```bash
cd examples/demo/frontend
npm install
npx playwright install chromium
DEMO_BACKEND_URL=http://127.0.0.1:4000 DEMO_FRONTEND_URL=http://127.0.0.1:3000 npm run test:e2e
```

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

### Ecto Sandbox Configuration

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

Configures Ecto for manual transaction management in tests. Ensure your test_helper.exs includes this setup.

```Elixir
use Ecto.Adapters.SQL.Sandbox, repo: Rulestead.Repo, mode: :manual
```

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

### Elixir GenServer for Runtime State

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

Start a process (like a GenServer) only when it models runtime characteristics such as connection ownership, rate limiting, or background state management. Avoid using processes solely for code organization.

```elixir
defmodule MyWorker do
  use GenServer

  # Client API
  def start_link(opts) do
    GenServer.start_link(__MODULE__, :ok, opts)
  end

  # Server callbacks
  def init(:ok) do
    {:ok, %{}} # Initial state
  end

  # ... other callbacks like handle_call, handle_cast
end
```

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

### OpenSearch Library API Layer Split

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

An example of how to apply the layered architecture to an OpenSearch library. This defines distinct modules for different responsibilities, enhancing modularity.

```elixir
•	OpenSearch — public API
•	OpenSearch.Client — client/config struct
•	OpenSearch.Transport — behaviour
•	OpenSearch.Transport.Finch — adapter
•	OpenSearch.Request / OpenSearch.Response
•	OpenSearch.Error
•	OpenSearch.Telemetry
•	OpenSearch.Testing or test helpers
```

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

### Publish Ruleset to Enable Flag Globally (Rulestead)

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

Example of publishing a ruleset in Rulestead to achieve the equivalent of enabling a flag globally. This demonstrates Rulestead's declarative and auditable approach.

```elixir
alias Rulestead.Store.Command.PublishRuleset

Rulestead.publish_ruleset(%PublishRuleset{
  environment_key: "production",
  flag_key: "my_feature",
  rules: [
    %{id: "rule-1", action: "return_true", conditions: []}
  ],
  actor: %{"user" => "admin@example.com"},
  reason: "Enabling feature globally"
})
```

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

### Elixir Library Supervision Tree Integration

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

Libraries should provide a first-class supervised component using modern child specs for clean integration into Elixir supervision trees. This example shows the typical shape of a child spec for a client module.

```elixir
children = [
  {OpenSearch.Client, name: MyApp.OpenSearch, base_url: "...", ...}
]
```

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

### Phoenix LiveView Mount with Context

Source: https://github.com/sztheory/rulestead/blob/main/guides/recipes/context-propagation.md

Pass bounded context values during LiveView mount and rebuild the context from socket assigns and session data. This example shows assigning context and current user, then using assign_flags.

```elixir
def mount(_params, session, socket) do
  socket = 
    assign(socket, 
      rulestead_context: socket.assigns[:rulestead_context],
      current_user: socket.assigns[:current_user]
    )

  {:ok, 
   Rulestead.LiveView.assign_flags(
     socket, 
     %{checkout_enabled: "checkout-redesign"},
     session: session
   )}
end
```

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

### Installer Golden Job Configuration

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

This YAML configuration defines the 'installer_golden' job, which runs only if the 'installer_path_gate' job determines it's necessary. It sets up the environment, checks out code, configures Elixir, and runs specific installer-related tests.

```yaml
installer_golden:
  needs: installer_path_gate
  if: needs.installer_path_gate.outputs.run == 'true'
  runs-on: ubuntu-24.04
  timeout-minutes: 10
  services: { postgres: ... }
  steps:
    - uses: actions/checkout@...
    - uses: erlef/setup-beam@v1
      with: { version-file: .tool-versions, version-type: strict }
    - run: mix deps.get
    - run: mix test test/rulestead/install/golden_diff_test.exs --include golden
```

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

### 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
```

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

### CI Job for Host-App Smoke Tests

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

A GitHub Actions CI job configuration for running the host-app smoke tests. It includes checking out code, setting up the Elixir environment, and running project dependencies, database migrations, and tests for the example application.

```yaml
integration:
  runs-on: ubuntu-24.04
  services: { postgres: ... }
  steps:
    - uses: actions/checkout@...
    - uses: erlef/setup-beam@v1
    - run: |
        cd test/example
        mix deps.get
        mix ecto.create
        mix ecto.migrate
        mix test
        scripts/ci/admin-acceptance-smoke.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: [...] 
)
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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)
```

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

### 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
```

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

### 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
```

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

### 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={...}>
```

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

### 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 \\ [])
```

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

### 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)
```

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

### Enable Feature Flag for Group (FunWithFlags)

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

Example of imperatively enabling a feature flag for a specific group in FunWithFlags.

```elixir
FunWithFlags.enable(:my_feature, for_group: :admins)
```

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

### Enable Feature Flag for Actor (FunWithFlags)

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

Example of imperatively enabling a feature flag for a specific actor in FunWithFlags.

```elixir
FunWithFlags.enable(:my_feature, for: user)
```

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

### Evaluate Feature Flag for an Actor (FunWithFlags)

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

Example of checking if a feature flag is enabled for a specific actor in FunWithFlags.

```elixir
FunWithFlags.enabled?(:my_feature, for: user)
```

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

### Run Post-GA Band Closure Proof

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

Execute the command for post-GA band closure proof. This is used when closing v1.10 support truth or validating documentation, release contracts, and the v1.9 proof superset alignment.

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

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

### Add a new flag

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

Command to add a new flag with a default value and environment specification. Useful for initial setup.

```bash
mix rulestead.add_flag checkout_v2 --default false --env dev
```

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

### Build Docs with Warnings as Errors

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

Generate project documentation and fail the build if documentation warnings are present. This ensures that documentation is accurate and complete.

```elixir
mix docs --warnings-as-errors
```

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

### Evaluate Feature Flag with Context (Rulestead)

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

Example of checking if a feature flag is enabled in Rulestead, always requiring a context map.

```elixir
Rulestead.enabled?(:my_feature, %{"user_id" => "123", "role" => "admin"})
```

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

### CI Test Command

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

The mix ci.all command provides a fast local CI experience, benefiting OSS Contributors like Omar.

```bash
mix ci.all
```

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

### Run Guarded Rollout Auto-Advance Proof (Primary Command)

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

Run the primary maintainer command for the guarded rollout auto-advance proof. Ensure you are in the 'rulestead' directory.

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

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

### Get a flag value

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

Fetches a complex value, such as JSON configuration, associated with a flag. Provides a default if the flag is not found or has no value.

```elixir
%{timeout_ms: ..., rate_limit: ...} = Rulestead.get_value("checkout_config", ctx, default: @defaults)
```

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

### Run Mounted Companion Contract Proof

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

Execute the mounted companion contract proof locally or in CI. This scope is intentionally bounded to specific test files related to admin contracts and audience components.

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

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

### CSS Custom Properties for Styling

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

Use CSS custom properties exclusively for styling to avoid shipping fork-required CSS setups and ensure maintainability.

```elixir
Don't ship a fork-required CSS setup — CSS custom properties only
```

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

### Run Guarded Rollout Foundations Proof

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

Execute the guarded rollout foundations proof locally. This scope is bounded to tests verifying VER-01 support truth, guardrail decision semantics, and mounted rollout status explanation.

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

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

### Run Blast Radius Governance Proof (CI Wrapper)

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

Use the CI wrapper to rerun the blast radius governance proof. This command applies a specific test scope for bounded verification.

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

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

### Run Maintainer Release Prep Checks

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

Perform repository hygiene checks before preparing a release. Use `--skip-mix-ci` to only run repo checks without Mix CI.

```bash
./scripts/maintainer/repo_hygiene_check.sh
```

```bash
./scripts/maintainer/repo_hygiene_check.sh --skip-mix-ci
```

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

### Get Specific Evaluation Results

Source: https://github.com/sztheory/rulestead/blob/main/guides/flows/evaluation.md

Uses projection helpers to retrieve specific pieces of information from a flag evaluation, such as enabled status, value, variant, or explanation.

```elixir
{:ok, enabled?} = Rulestead.enabled?(flag_payload, context)
{:ok, value} = Rulestead.get_value(flag_payload, context, %{timeout_ms: 500})
{:ok, variant} = Rulestead.get_variant(flag_payload, context)
{:ok, explanation} = Rulestead.explain(flag_payload, context)
```

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

### Run Blast Radius Governance Proof (Primary Command)

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

Execute the primary maintainer command for the blast radius governance proof. Navigate to the 'rulestead' directory before running.

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

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

### Rulestead.TestHelpers Ergonomics

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

The Rulestead.TestHelpers module provides convenient functions and macros to simplify the use of Rulestead.Fake within ExUnit tests, ensuring proper setup and cleanup.

```APIDOC
## Module: Rulestead.TestHelpers

### Description

Provides public test helpers that wrap `Rulestead.Fake` with ExUnit ergonomics. These helpers are treated as part of the public API and are documented for use in host applications' tests.

### Test Helpers

- **`with_flag(key, value, test_fn)`**: Sets a flag's value for the duration of a test function. The flag is automatically removed after the test completes using `on_exit`.
  - **`key`**: The key of the flag.
  - **`value`**: The value to set for the flag.
  - **`test_fn`**: The test function to execute.

- **`put_flag(key, attrs)`**: Persists a flag in the `Rulestead.Fake` store for the remainder of the current test.
  - **`key`**: The key of the flag.
  - **`attrs`**: A map of attributes for the flag.

- **`clear_flags()`**: Clears all flags from the `Rulestead.Fake` store. Use sparingly, preferring targeted cleanup.

- **`seed_bucket(flag_key, actor_id, variant)`**: Forces a specific actor to bucket into a known variant for a given flag.
  - **`flag_key`**: The key of the flag.
  - **`actor_id`**: The ID of the actor.
  - **`variant`**: The variant to force the actor into.

### Macros

- **`assert_flag_evaluated(flag_key, do: block)`**: Asserts that a flag was evaluated during the execution of the provided code block. It checks the count of recorded evaluations before and after the block and verifies that the specified flag key is present in the evaluations.
  - **`flag_key`**: The key of the flag to assert evaluation for.
  - **`block`**: The code block to execute and monitor for flag evaluations.
```

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

### Run Guarded Rollout Auto-Advance Proof (CI Wrapper)

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

Rerun the guarded rollout auto-advance proof using the CI wrapper. This command utilizes a specific test scope for bounded verification.

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

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

### Initialize OpenFeatureRulestead Provider

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

Initialize the OpenFeatureRulestead provider with an explicit OpenFeature domain (environment_key) and set it as the default provider.

```elixir
provider = %OpenFeatureRulestead.Provider{}

{:ok, provider} =
  OpenFeatureRulestead.Provider.initialize(provider, "production", %{})

OpenFeature.set_provider(provider, domain: "production")
```

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

### Custom Rulestead Admin Policy Implementation

Source: https://github.com/sztheory/rulestead/blob/main/guides/flows/extending-rulestead.md

Example of implementing the Rulestead.Admin.Policy behaviour to integrate with a custom authorization system. This keeps the `can?/4` function as the boundary for auth decisions.

```elixir
defmodule MyApp.RulesteadPolicy do
  @behaviour Rulestead.Admin.Policy

  @impl true
  def can?(actor, action, _resource, environment_key) do
    MyApp.Authorizer.allowed?(actor, action, environment_key)
  end
end
```

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

### Run Reusable Targeting Deepening Proof (Primary Command)

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

Use this command to run the primary maintainer command for the reusable targeting deepening proof. Ensure you are in the 'rulestead' directory.

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

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

### Manual Hex Package Publishing Workflow

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

This workflow allows for manual publishing of Hex packages using `workflow_dispatch`. It requires explicit tag and version inputs and follows a similar gate chain to release-please.

```yaml
name: publish-hex
on:
  workflow_dispatch:
    inputs:
      tag:
        required: true
        description: "Git tag to publish from (e.g. v0.3.1)"
      release_version:
        required: true
        description: "Version number (e.g. 0.3.1) — must match @version in mix.exs"

permissions:
  contents: read

jobs:
  publish:
    runs-on: ubuntu-24.04
    services: { postgres: ... }
    env:
      HEX_API_KEY: ${{ secrets.HEX_API_KEY }}
    steps:
      - uses: actions/checkout@...
        with: { ref: ${{ inputs.tag }}, fetch-depth: 0 }
      - uses: erlef/setup-beam@v1
        with: { version-file: .tool-versions, version-type: strict }
      - name: Verify version matches tag
        run: grep -n "@version \"${{ inputs.release_version }}\"" mix.exs
      - run: mix deps.get
      - run: mix verify.workspace_clean
      - run: mix test
      - run: mix hex.publish --dry-run
      - run: mix hex.publish --yes
      - name: Post-publish verify
        run: |
          mix verify.release_publish "${{ inputs.release_version }}"
          mix verify.release_parity "${{ inputs.release_version }}"
```

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

### Dialyzer PLT Cache Configuration

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

Configures Dialyzer to use a local PLT cache for faster analysis. This is part of a recommended CI setup for strict type checking.

```elixir
plt_local_path: "priv/plts"
```

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

### Supervisor Strategies and Restart Semantics

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

Choose appropriate supervisor strategies (:one_for_one, :one_for_all, :rest_for_one) and child restart semantics (:permanent, :transient, :temporary) based on child process coupling and expected behavior.

```elixir
# Practical strategy choices
#	• :one_for_one: default for most libraries
#	• :rest_for_one: when later children depend on earlier ones
#	• :one_for_all: only when children are tightly coupled and should restart together
```

```elixir
# Child restart semantics matter
#
# Supervisor docs define:
#	• :permanent — always restart
#	• :transient — restart only on abnormal exit
#	• :temporary — never restart
```

```elixir
# For libraries:
#	• connection pool manager / credential refresher: often :permanent
#	• one-shot task-like child: :temporary
#	• worker where normal completion is expected: maybe :transient
```

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

### Generate Documentation

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

Generates project documentation using the `mix docs` command. This is part of the code quality and maintainability workflow.

```bash
cd rulestead && mix docs
```

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

### Evaluate Global Feature Flag with Empty Context (Rulestead)

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

Example of checking a global feature flag in Rulestead, which still requires an explicit (even if empty) context map.

```elixir
Rulestead.enabled?(:global_feature, %{})
```

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

### Start Telemetry Span for Decision Evaluation

Source: https://github.com/sztheory/rulestead/blob/main/prompts/rulestead-telemetry-observability-and-audit.md

Initiates a telemetry span for the flag evaluation process. Includes initial metadata about the flag and context. The span automatically captures duration and exceptions.

```elixir
:telemetry.span(
  [:rulestead, :eval, :decide],
  %{flag_key: flag_key, tenant_id: ctx.tenant_id, env: ctx.env, trace_id: ctx.trace_id},
  fn ->
    result = Evaluator.decide(flag_key, ctx)
    stop_metadata = %{
      variant: result.variant,
      matched_rule_index: result.matched_rule_index,
      bucket: result.bucket,
      reason: result.reason,
      cache_source: result.cache_source
    }
    {result, stop_metadata}
  end
)
```

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

### Conflict Handling Output

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

This output indicates a conflict where Rulestead could not find an expected injection zone. It suggests manual merging of changes from a sidecar file and advises re-running the installer.

```text
[rulestead]  ~ conflict: lib/my_app/application.ex
             Could not find expected injection zone.
             Wrote intended changes to:
               lib/my_app/application.ex.rulestead_conflict
             Please review + merge manually, then re-run the installer.
             See: https://hexdocs.pm/rulestead/troubleshooting/conflicts.html

[rulestead] 1 conflict(s). Aborting.
```

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

### Explain Flag Permalink

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

The /admin/flags/:key/explain endpoint provides a permalinkable and fast way to explain feature flag decisions, serving Sam's need for supportability.

```http
/admin/flags/:key/explain?actor=...
```

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

### Seed Fake State for the Current Test

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

Use `put_flag/3` to set a flag value that persists for the remainder of the current test. `clear_flags/0` is recommended in a `setup` block to ensure test isolation.

```elixir
setup do
  clear_flags()
  :ok
end

test "returns the forced value from the fake-backed contract" do
  put_flag("beta-banner", false, environment: "test")

  assert {:ok, false} =
           Rulestead.Runtime.enabled?
             ("test",
              "beta-banner",
              %{targeting_key: "user-123", environment: "test"})
end
```

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

### Database Insert Query Log

Source: https://github.com/sztheory/rulestead/blob/main/rulestead/test_out.txt

Logs a successful database insertion into the 'runtime_snapshots' table. This query is part of the promotion apply process.

```elixir
19:06:46.568 [debug] QUERY OK source="runtime_snapshots" db=0.1ms
INSERT INTO "runtime_snapshots" ("version","metadata","environment_key","published_at","payload","payload_checksum","inserted_at","updated_at","id") VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9) [2, %{schema_version: 1, flag_count: 1}, "test", ~U[2026-05-19 17:06:46.564114Z], <<131, 116, 0, 0, 0, 4, 119, 5, 102, 108, 97, 103, 115, 116, 0, 0, 0, 1, 109, 0, 0, 0, 17, 99, 104, 101, 99, 107, 111, 117, 116, 45, 114, 101, 100, 101, 115, 105, 103, 110, 116, 0, 0, 0, 5, 119, 4, 102, 108, 97, 103, 116, 0, 0, 0, 13, 119, 2, 105, 100, 109, 0, 0, 0, 36, 54, 48, 57, 100, 51, 53, 51, 98, 45, 50, 100, 48, 55, 45, 52, 100, 53, 53, 45, 56, 57, 51, 99, 45, 98, 51, 97, 48, ...>>]
 [90m↳ Rulestead.Store.Ecto.run_promotion_apply/2, at: lib/rulestead/store/ecto.ex:133 [0m
```

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

### Explaining Feature Flag Evaluation in Elixir

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

Use `Flags.explain/2` to get a detailed breakdown of a flag's evaluation result. This is crucial for debugging and understanding why a specific flag returned a certain value.

```elixir
{:ok, result} = Flags.explain(:new_checkout, context)
```

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

### Create Bounded Context for Explainability

Source: https://github.com/sztheory/rulestead/blob/main/guides/flows/explainability.md

Construct a Rulestead context object for explainability requests. Ensure it includes only the necessary targeting key, environment, and relevant attributes.

```elixir
context =
  Rulestead.Context.new(
    targeting_key: "user_123",
    environment: "prod",
    attributes: %{country: "US", plan: "pro"}
  )
```

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

### Basic Feature Flag Checks in Elixir

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

Use these functions for simple boolean checks, retrieving string values with defaults, and getting variant information for experiments. Ensure a context is provided for evaluation.

```elixir
if Flags.enabled?(:new_checkout, context) do
  ...
end

color =
  Flags.get_string(:checkout_button_color, "blue", context)

variant =
  Flags.get_variant(:checkout_experiment, context)

explanation =
  Flags.explain(:checkout_experiment, context)
```

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

### Configure Preview Evidence Resolver

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

Register a custom preview evidence resolver by setting the `:preview_evidence_resolver` in your Rulestead configuration. If unset, previews rely on authored state and explicit samples.

```elixir
config :rulestead, :preview_evidence_resolver, MyApp.RulesteadPreviewEvidence
```

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

### Test flag behavior in isolation

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

Provides test helpers to temporarily enable or set flag states within a test's execution context, avoiding the need for a full environment setup.

```elixir
with_flag "checkout_v2", true, do: ... end
```

```elixir
put_flag "pricing_exp", %{variant: "treatment"}
```

```elixir
seed_bucket "pricing_exp", "u_123", "treatment"
```

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

### Telemetry Span Naming Convention

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

Defines the 4-level event naming structure for telemetry spans, including the :start, :stop, and :exception suffixes. Use :crypto.hash(:sha256, actor_id) for correlation without PII.

```Elixir
[:rulestead, :domain, :resource, :action, :start | :stop | :exception]
```

```Elixir
[:rulestead, :eval, :decide, :stop]
```

```Elixir
[:rulestead, :admin, :ruleset, :published]
```

```Elixir
:crypto.hash(:sha256, actor_id)
```

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

### Run Post-GA Band Closure Proof via Integrator Alias

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

Use the integrator-facing alias to run the post-GA band closure proof. This command delegates to phase82 and is an alternative for current merges.

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

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

### Run Tests from Package Directories

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

Runs tests specifically within the 'rulestead' and 'rulestead_admin' package directories. This allows for targeted testing of individual components.

```bash
# sibling packages
cd rulestead && mix test
cd ../rulestead_admin && mix test
```

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

### Admin Feature Module

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

Defines the Admin UI feature for Rulestead installation. It's applicable unless the '--no-admin' flag is present and injects the admin mount, scaffolds policies, and links static assets.

```elixir
defmodule Rulestead.Install.Features.Admin do
  @behaviour Rulestead.Install.Feature

  @impl true
  def applicable?(%{flags: flags}), do: "--no-admin" not in flags
  @impl true
  def description, do: "Admin UI (mountable LiveView at /admin/flags)"

  @impl true
  def apply(state) do
    state
    |> Rulestead.Install.Router.inject_admin_mount()
    |> Rulestead.Install.Policy.scaffold()
    |> Rulestead.Install.Assets.link_admin_static()
  end

  @impl true
  def rollback(state), do: state   # optional; used by uninstall
end
```

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

### Define Rulestead Admin Authorization Policy

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

Implement custom authorization logic for the Rulestead admin interface. This example shows how to require specific roles for production actions and enforce change requests for rule publishes.

```elixir
defmodule MyApp.RulesteadAdminPolicy do
  @moduledoc """
  Authorization policy for the rulestead admin surface.

  Generated by `mix rulestead.install`. Reference implementation:
  `Rulestead.Admin.Policy.RoleBased`. Override actions below to encode
  your team's rules.
  """

  use Rulestead.Admin.Policy.RoleBased

  # Example: require :incident_commander role to engage prod kill switches.
  @impl Rulestead.Admin.Policy
  def authorize(:engage_killswitch, %Rulestead.Context{env: :prod, actor: %{roles: roles}}, _res) do
    if :incident_commander in roles, do: :ok, else: {:error, :forbidden}
  end

  def authorize(action, ctx, res), do: super(action, ctx, res)

  # Example: require change-request for prod ruleset publishes.
  @impl Rulestead.Admin.Policy
  def change_request_required?(:publish_ruleset, %Rulestead.Context{env: :prod}, _), do: true
  def change_request_required?(action, ctx, res), do: super(action, ctx, res)
end
```

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

### Run CI and Verifier in Rulestead Project

Source: https://github.com/sztheory/rulestead/blob/main/prompts/bump-peer-sztheory-deps-prompt.txt

Performs continuous integration checks and verifies adopter status within the 'rulestead' project directory.

```bash
cd rulestead && mix ci && mix verify.adopter
```

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

### LiveView Latency Simulation

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

For modern UX, always design and test under latency. LiveView's docs explicitly recommend using the built-in latency simulator because localhost hides real interaction problems.

```Elixir
latency simulator
```

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

### Include Admin UI Stylesheet

Source: https://github.com/sztheory/rulestead/blob/main/guides/flows/admin-ui.md

Include the packaged stylesheet in your host root layout to ensure the Admin UI renders correctly. This typically involves copying the CSS file into your asset pipeline.

```heex
<link phx-track-static rel="stylesheet" href={~p"/assets/css/rulestead_admin.css"} />
```

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

### Using Supervisor for Static Child Trees

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

Use the standard Supervisor for managing mostly static child processes within a supervision tree.

```elixir
# Use for mostly static child trees.
```
Tokens:
Raw