### Install Dependencies and Start Dev Server

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/readme.md

Use this command to install project dependencies and start the local development server for the Avo documentation site.

```bash
yarn install && yarn dev
```

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

### Guide Frontmatter with API Docs Link

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/contributing/writing-docs.md

Example of frontmatter for a guide page, including a link to its corresponding API reference page.

```yaml
---
license: pro
outline: [2, 3]
api_docs: ./feature-api.html
---
```

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

### Install Avo::Meta Migrations

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/avo-meta.md

Install the necessary database migrations for Avo::Meta to create the required tables.

```bash
$ bin/rails avo_meta:install:migrations
$ bin/rails db:migrate

```

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

### Action Generation Examples

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/actions/generator.md

These examples demonstrate generating regular actions, standalone actions, and actions within namespaces.

```bash
# Generate a regular action
bin/rails generate avo:action mark_as_featured
```

```bash
# Generate a standalone action
bin/rails generate avo:action generate_monthly_report --standalone
```

```bash
# Generate an action in a namespace
bin/rails generate avo:action admin/approve_user
```

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

### Frontmatter Configuration

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/AGENTS.md

Example frontmatter for a guide page, specifying license, outline depth, and API documentation link.

```yaml
---
license: pro          # community | pro
outline: [2, 3]       # h2 + h3 in the "On this page" panel; or `deep`
api_docs: ./feature-api.html   # link to the reference; omit if guide-only
---

```

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

### Example Prompt with MCP Server

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/common/llm-support/windsurf-common.md

An example of how to structure a prompt to Windsurf when using a configured MCP server like Context7.

```bash
create a new Avo resource for a product model. use context7
```

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

### Install Gems

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/http-resources.md

After adding the gem to your Gemfile, run `bundle install` to install all project dependencies, including the `avo-http_resource` gem.

```bash
bundle install

```

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

### Install Avo Collaboration Migrations

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/collaboration/overview.md

Run the install migrations command to generate the necessary database migrations for collaboration.

```bash
rails avo_collaboration:install:migrations
```

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

### Install avo-kanban Gem

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/kanban-boards.md

Run this command in your terminal after adding the gem to your Gemfile to install it.

```bash
bundle install
```

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

### Install Dependencies and Make CLI Executable

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/README-vitepress-llms-concatenator.md

Install project dependencies using npm or yarn, then make the CLI script executable.

```bash
# Install dependencies
npm install
# or
yarn install

# Make CLI executable
chmod +x scripts/generate-llms-txt.js
```

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

### Install Avo with One-Command App Template

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/installation.md

Use this command to install Avo via a Rails app template for a streamlined setup process.

```bash
bin/rails app:template LOCATION='https://avohq.io/app-template'
```

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

### Install Pundit

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authorization.md

Run this command to install Pundit if it's not already set up in your application.

```bash
bin/rails g pundit:install
```

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

### ActionCable Configuration Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/notifications.md

Example configuration for ActionCable in a Rails application. Ensure this is set up for real-time notification delivery.

```yaml
development:
  adapter: async

production:
  adapter: redis
  url: redis://localhost:6379/1
```

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

### Install Solid Cache Migrations

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/cache.md

Run the Solid Cache migration generator and then migrate the database to set up Solid Cache.

```bash
bin/rails solid_cache:install:migrations
```

```bash
bin/rails db:migrate
```

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

### Install Avo with Jumpstart Pro Template

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/installation.md

Use this template to add Avo to a Jumpstart Pro application.

```ruby
bin/rails app:template LOCATION=https://v3.avohq.io/templates/jumpstart-pro.template
```

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

### Example for User Resource

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/mount.md

This example demonstrates the specific endpoints generated for a `User` resource, illustrating the application of the standard endpoint pattern.

```APIDOC
## Example for User Resource

If you have an `Avo::Resources::User` resource:

```
GET    /api/resources/v1/users     # List users
POST   /api/resources/v1/users     # Create user
GET    /api/resources/v1/users/1   # Show user
PATCH  /api/resources/v1/users/1   # Update user
PUT    /api/resources/v1/users/1   # Update user
DELETE /api/resources/v1/users/1   # Delete user
```
```

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

### Full Discreet Information Configuration Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/discreet-information.md

An example demonstrating a comprehensive configuration of discreet information with various options like text, badges, key-value pairs, icons, URLs, and visibility.

```ruby
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
  self.discreet_information = [
    :id,
    :timestamps,
    :created_at,
    :updated_at,
    {
      text: "label",
      as: :badge,
      title: -> { sanitize("View <strong>#{record.name}</strong> on site", tags: %w[strong]) },
      icon: -> { "heroicons/outline/arrow-top-right-on-square" },
      url: -> { main_app.root_url },
      target: :_blank
    },
    {
      text: -> { "Simple text #{record.id}" },
      as: :text,
      title: -> { sanitize("View <strong>#{record.name}</strong> on site", tags: %w[strong]) },
      icon: -> { "tabler/outline/external-link" },
      url: -> { main_app.root_url },
      visible: true
    },
    {
      text: "Test",
      as: :badge,
      visible: false
    },
    {
      as: :key_value,
      key: "Key",
      value: "Value"
    },
    {
      as: :icon,
      icon: "tabler/outline/cube-3d-sphere",
      title: -> { Time.now }
    }
  ]

  # fields and other resource configuration
end
```

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

### General Settings Sub-Page Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/forms-and-pages/pages.md

Example of a sub-page for general settings, containing forms for application and company information.

```ruby
# app/avo/pages/settings/general.rb
class Avo::Pages::Settings::General < Avo::Forms::Core::Page
  self.title = "General Settings"
  self.description = "Basic application configuration"

  def content
    form Avo::Forms::Settings::AppSettings
    form Avo::Forms::Settings::CompanyInfo
  end
end
```

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

### API Index Query Parameters Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/index.md

Demonstrates how to use query parameters for pagination and sorting in API index requests.

```bash
GET /api/resources/v1/teams?page=2&per_page=10&sort_by=name&sort_direction=asc
```

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

### API Option Reference Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/contributing/writing-docs.md

Structure for documenting a single configuration option in the API reference. Includes the option name, description, code example, type, and default value.

```markdown
<Option name="`logo_dark`">

Path to the dark-mode variant of the main logo. When omitted, `logo` is used in both schemes.

```ruby
config.appearance = {
  logo_dark: "my_company/logo-dark.png"
}
```

- **Type:** String
- **Default:** `nil`

</Option>
```

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

### Example Custom Search Provider Implementation

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/search/global-search.md

This Ruby example demonstrates how to configure Avo's global search to use a custom provider by defining a `query` block that returns an array of custom search result hashes.

```ruby
class Avo::Resources::Project < Avo::BaseResource
  self.search = {
    query: -> do
      [
        { _id: 1, _label: "Record One", _url: "https://example.com/1" },
        { _id: 2, _label: "Record Two", _url: "https://example.com/2" },
        { _id: 3, _label: "Record Three", _url: "https://example.com/3" }
      ]
    end
  }
end
```

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

### Cross-linking Guide to API Reference

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/AGENTS.md

Use the `api_docs` frontmatter key to link from a guide page to its corresponding API reference page. This renders a specific callout.

```markdown
Provide [`logo_dark`](./appearance-api.html#logo_dark) to render a different file in dark mode.
```

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

### Run Avo Audit Logging Installer

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/audit-logging/index.md

Execute the Avo audit logging installer command to generate necessary migrations, resources, and controllers for activity tracking.

```bash
bin/rails generate avo:audit_logging install

```

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

### Action Policy example policy

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authorization.md

Example of an Avo-namespaced equipment policy using Action Policy. Define methods like `index?`, `new?`, and `create?` to control access.

```ruby
# app/policies/avo/equipment_policy.rb
module Avo
  class EquipmentPolicy < ApplicationPolicy
    def index?
      true
    end

    def new?
      user.admin?
    end

    def create?
      user.admin?
    end
  end
end
```

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

### Example API Endpoints for User Resource

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/mount.md

This example illustrates the generated endpoints specifically for an Avo::Resources::User resource, showing how the resource name is substituted into the URL.

```shell
GET    /api/resources/v1/users     # List users
POST   /api/resources/v1/users     # Create user
GET    /api/resources/v1/users/1   # Show user
PATCH  /api/resources/v1/users/1   # Update user
PUT    /api/resources/v1/users/1   # Update user
DELETE /api/resources/v1/users/1   # Delete user
```

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

### Example Custom Content in Profile Menu Partial

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/menu-editor.md

An example of how to render a custom profile item within the ejected `_profile_menu_extra.html.erb` partial.

```erb
<%# Example link below %>
<%#= render Avo::ProfileItemComponent.new label: 'Profile', path: '/profile', icon: 'user-circle' %>
```

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

### CORS Configuration Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/index.md

Shows how to configure CORS for API access from web applications using the `rack-cors` gem.

```ruby
# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*'
    resource '/api/*',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options, :head]
  end
end
```

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

### Action Policy Client Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authorization.md

A complete example of an Action Policy client that adheres to Avo's authorization contract, including configuration.

```APIDOC
### Action Policy example

Here is a complete Action Policy client that follows Avo's contract:

```ruby
# app/services/avo/action_policy_authorization_client.rb
module Avo
  class ActionPolicyAuthorizationClient
    include ::ActionPolicy::Behaviour

    authorize :user
    attr_accessor :user

    def authorize(user, record, action, policy_class: nil, **)
      self.user = user
      authorize!(record, to: action, with: policy_class)
    rescue ActionPolicy::Unauthorized => error
      raise Avo::NotAuthorizedError, error.message
    end

    def policy(user, record, **)
      policy!(user, record)
    rescue Avo::NoPolicyError
      nil
    end

    def policy!(user, record, **)
      self.user = user
      policy_for(record:)
    rescue ActionPolicy::NotFound => error
      raise Avo::NoPolicyError, error.message
    end

    def apply_policy(user, model, policy_class: nil, **)
      policy = if policy_class.present?
        policy_class.new(model, user:)
      else
        policy!(user, model)
      end

      policy.apply_scope(model, type: :active_record_relation)
    end
  end
end
```

Place your policies under the `Avo` namespace (for example `Avo::EquipmentPolicy`) or configure Action Policy's lookup to match your app.

```ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.authorization_client = "Avo::ActionPolicyAuthorizationClient"
end
```

```ruby
# app/policies/avo/equipment_policy.rb
module Avo
  class EquipmentPolicy < ApplicationPolicy
    def index?
      true
    end

    def new?
      user.admin?
    end

    def create?
      user.admin?
    end
  end
end
```
```

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

### Feature Documentation Model: Guide and Reference Pages

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/AGENTS.md

When a feature has a significant configuration surface, it requires two distinct pages: a guide for 'how-to' questions and a reference API page for detailed option explanations. This structure ensures comprehensive documentation for users.

```markdown
| Page | File | Answers | Organized by |
| --- | --- | --- | --- |
| **Guide** | `feature.md` | "How do I do X?" | task |
| **Reference (API)** | `feature-api.md` | "What exactly is option Y?" | option |
```

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

### Configure Profile Photo Source Using a Symbol

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/avatar.md

This example demonstrates configuring the `profile_photo` source by directly referencing a record field using a symbol.

```ruby
self.profile_photo = {
  source: :profile_photo # this will run `record.profile_photo`
}
```

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

### Generate Avo API Installers

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/index.md

Run the rails generate command to set up your API controllers and related files.

```bash
rails generate avo_api:install

```

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

### Link with Path

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/native-components/avo-button-component.md

Example of rendering a link using the `a_link` helper with a specified path.

```erb
<%= a_link("/admin") { "Admin" } %>
```

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

### Install Gems with Authentication in Dockerfile

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/gem-server-authentication.md

Use a Dockerfile to install application gems, mounting the BUNDLE_PACKAGER__DEV secret. This ensures that bundler can authenticate with the gem server during installation.

```dockerfile
# Install application gems
COPY Gemfile Gemfile.lock ./

RUN --mount=type=secret,id=BUNDLE_PACKAGER__DEV BUNDLE_PACKAGER__DEV=$(cat /run/secrets/BUNDLE_PACKAGER__DEV) bundle install  && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
    bundle exec bootsnap precompile --gemfile
```

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

### Post Policy with Show Method Only

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authorization.md

Example of a policy class that only defines the `show?` method. When `explicit_authorization` is true, other actions like `index?` will be unauthorized.

```ruby
class PostPolicy < ApplicationPolicy
  def show?
    user.admin?
  end
end
```

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

### Create/Update Success Response

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/index.md

Example response for a successful resource creation or update operation. Returns the created or updated record's basic information.

```json
{
  "record": {
    "id": 3,
    "name": "New Team",
    "url": "https://new.company.com"
  }
}
```

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

### Database Payload Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/fields/boolean_group.md

An example of a boolean group object as it would be stored in the database.

```ruby
{
  "admin": true,
  "manager": true,
  "writer": true,
}
```

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

### Setup Rails App and Change Path

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/guides/run-avo-on-the-root-path.md

Commands to create a new Rails application, apply the Avo template, and update the Avo initializer to set the root path to '/'.

```bash
rails new avo-root-path
cd avo-root-path
bin/rails app:template LOCATION='https://avohq.io/app-template'
sed -i '' "s|config.root_path = '/avo'|config.root_path = '/'|" config/initializers/avo.rb
```

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

### Comprehensive Header Menu Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/header-menu.md

A realistic mix of header menu link configurations, including positional paths, external links, query parameters, non-GET methods, and conditional visibility.

```ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.header_menu = -> {
    # Positional path
    link_to "Home", "/"

    # External link — :_blank gets an external-link icon automatically
    link_to "Docs", path: "https://docs.avohq.io", target: :_blank

    # Internal link with query params
    link_to "Drafts", path: avo.resources_posts_path, params: { status: "draft" }

    # Non-GET request via Turbo
    link_to "Sign out", path: main_app.destroy_user_session_path, method: :delete

    # Conditional — only renders for admins
    link_to "Admin tools", path: "/avo/tools", visible: -> {
      current_user.admin?
    }
  }
end
```

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

### Add Context7 MCP Server Command

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/common/llm-support/zed-common.md

This command installs and runs the Context7 MCP server, which provides libraries including Avo's documentation.

```bash
# server
npx -y @upstash/context7-mcp@latest
```

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

### Mount Avo with Default and Custom Paths

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/routing.md

Demonstrates how to mount Avo using the default path and how to specify a custom path using the `at` argument in `config/routes.rb`.

```ruby
# config/routes.rb
Rails.application.routes.draw do
  # Mounts Avo at Avo.configuration.root_path
  mount_avo

  # Mounts Avo at `/custom_path` instead of the default
  mount_avo at: "custom_path"
end
```

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

### Guard global hotkeys installation

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/plans/2026-04-02-001-feat-hotkey-configuration-plan.md

Prevents global hotkeys from being installed if the `enabled` configuration is false. This is an early exit mechanism.

```javascript
if (!Avo.configuration.hotkeys.enabled)
  return

```

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

### Include All Tools with `all_tools` Helper

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/menu-editor.md

This example shows how to use the `all_tools` helper within a section and group to render all available tools in the Avo application's menu.

```ruby
section "App", icon: "heroicons/outline/beaker" do
  group "All tools" do
    all_tools
  end
end
```

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

### Sample Resource Tool Partial

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/native-field-components.md

This ERB partial demonstrates the structure of a resource tool, including how to render Avo components and access available variables.

```erb
<div class="flex flex-col">
  <%= render Avo::PanelComponent.new title: "Post info" do |c|
    c.with_tools do %>
      <%= a_link('/avo', icon: 'heroicons/solid/academic-cap', style: :primary) do %>
        Dummy link
      <% end %>
    <% end %>
    c.with_body do %>
      <div class="flex flex-col p-4 min-h-24">
        <div class="space-y-4">
          <h3>🪧 This partial is waiting to be updated</h3>
          <p>
            You can edit this file here <code class='p-1 rounded bg-gray-500 text-white text-sm'>app/views/avo/resource_tools/post_info.html.erb</code>.
          </p>
          <p>
            The resource tool configuration file should be here <code class='p-1 rounded bg-gray-500 text-white text-sm'>app/avo/resource_tools/post_info.rb</code>.
          </p>
          <% 
            # In this partial, you have access to the following variables:
            # tool
            # @resource
            # @resource.model
            # form (on create & edit pages. please check for presence first)
            # params
            # Avo::Current.context
            # current_user
          %>
        </div>
      </div>
    <% end %>
  <% end %>
</div>
```

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

### Guard hotkey installation in application.js

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/plans/2026-04-02-001-feat-hotkey-configuration-plan.md

Conditionally installs hotkeys based on the `enabled` flag in the Avo configuration. This ensures hotkeys are only active when explicitly enabled.

```javascript
if (Avo.configuration.hotkeys.enabled)
  installHotkeys()

```

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

### Install Dependencies for VitePress LLMs Concatenator Development

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/README-vitepress-llms-concatenator.md

Set up the development environment for the VitePress LLMs Concatenator by installing project dependencies using npm.

```bash
npm install
```

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

### Full Page Example with Navigation, Forms, and Sub-Pages

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/forms-and-pages/pages.md

Defines a comprehensive settings page including a default sub-page, inline forms, and virtual pages for different configuration areas.

```ruby
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
  self.title = "Settings"
  self.description = "Manage your application settings"
  self.navigation_label = "App Settings"

  def navigation
    page Avo::Pages::Settings::General, default: true
    form Avo::Forms::UserProfiles
    page "Integrations",
      content: -> do
        form Avo::Forms::Settings::SlackIntegration
        form Avo::Forms::Settings::EmailIntegration
      end
    page Avo::Pages::Settings::Security
  end
end
```

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

### Development vs Production Setup

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/mount.md

Shows different configurations for mounting the Avo API in development and production environments, including enabling debugging routes in development.

```APIDOC
## Development vs Production Setup

```ruby
# config/routes.rb
Rails.application.routes.draw do
  mount_avo

  if Rails.env.development?
    # Development: Mount API with debugging routes
    mount_avo_api at: "/api" do
      get 'debug/info', to: proc { |env|
        info = {
          version: Avo::Api::VERSION,
          environment: Rails.env,
          timestamp: Time.current.iso8601
        }
        [200, { 'Content-Type' => 'application/json' }, [info.to_json]]
      }
    end
  else
    # Production: Simple mount
    mount_avo_api at: "/api"
  end
end
```
```

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

### Run Avo Notifications Installer

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/notifications.md

Execute the Rails generator to install Avo Notifications. This command sets up necessary files like migrations, initializers, and Avo resources.

```bash
bin/rails generate avo:notifications install

```

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

### Install Rails App Without Paid Gems

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/gem-server-authentication.md

Distribute your Rails application without paid gems by moving them to an optional group in your Gemfile and installing with `RAILS_GROUPS` and `BUNDLE_WITH`.

```bash
RAILS_GROUPS=avo BUNDLE_WITH=avo bundle install
```

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

### Advanced CLI Options and Arguments

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/README-vitepress-llms-concatenator.md

Understand the arguments and options available for the CLI tool, including version, configuration path, output path, and logging levels.

```bash
node scripts/generate-llms-txt.js [version] [options]

Arguments:
  version                     Version to process (4.0, 3.0, latest, all) (default: "latest")

Options:
  -V, --version              Display version number
  -h, --help                 Display help for command
  -c, --config <path>        Path to VitePress config file (default: "docs/.vitepress/config.js")
  -o, --output <path>        Output file path (default: "docs/public/llms.txt")
  -d, --docs-dir <path>      Documentation directory (default: "docs")
  --log-level <level>        Logging level (silent, error, warn, info, debug) (default: "info")
  --log-file <path>          Log to file
  --include-toc              Include table of contents
  --include-metadata         Include file metadata (default: true)
  --max-section-length <size> Maximum section length in characters
  --format <format>          Output format (markdown, text, llms_txt) (default: "llms_txt")
  --title <title>           Custom title for generated file
  --description <description> Custom description for generated file
  --dry-run                 Show what would be done without actually generating files
  --verbose                 Enable verbose output
```

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

### Run Database Migrations

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/collaboration/overview.md

Apply the generated migrations to your database to set up collaboration tables.

```bash
rails db:migrate
```

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

### Build Avo Assets from GitHub Installation

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/installation.md

When installing Avo from GitHub, you must compile assets. This Rakefile enhancement ensures Avo assets are built during the assets:precompile step.

```ruby
# Rakefile
Rake::Task["assets:precompile"].enhance do
  Rake::Task["avo:build-assets"].execute
end
```

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

### Configure Record Previews

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/record-previews.md

Add the `preview` field to your resource and use `show_on: :preview` to make fields visible in the preview popover. This example shows how to configure previews for a 'Team' resource.

```ruby
class Avo::Resources::Team < Avo::BaseResource
  def fields
    field :preview, as: :preview
    field :name,
     as: :text,
     sortable: true,
     show_on: :preview
    field :color,
      as: Avo::Fields::ColorPickerField,
      hide_on: :index,
      show_on: :preview
    field :description,
      as: :textarea,
      show_on: :preview
  end
end
```

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

### Configure Main Menu for All Activities Overview

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/audit-logging/index.md

To provide an overview of all activities in Avo, configure the main menu in `config/initializers/avo.rb` to include a section for `avo_activity`.

```ruby
# config/initializers/avo.rb

Avo.configure do |config|
  config.main_menu = -> {
    section "AuditLogging", icon: "presentation-chart-bar" do
      resource :avo_activity
    end
  }
end
```

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

### Repetitive Filter Code Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/dynamic-filters.md

Demonstrates a common problem where filter logic is repeated across multiple fields, violating the DRY principle. This example shows repetitive filter configurations for JSON fields.

```ruby
class Avo::Resources::Feedback < Avo::BaseResource
  def fields
    field :company_size, filterable: {
      type: :select,
      options: -> { Feedback.pluck(Arel.sql("answers->>'company_size'")).uniq },
      query: -> { query.where(Arel.sql("answers->>'company_size' = '#{filter_param.value}'")) }
    }

    field :company_industry, filterable: {
      type: :select,
      options: -> { Feedback.pluck(Arel.sql("answers->>'company_industry'")).uniq },
      query: -> { query.where(Arel.sql("answers->>'company_industry' = '#{filter_param.value}'")) }
    }

    field :title, filterable: {
      type: :select,
      options: -> { Feedback.pluck(Arel.sql("answers->>'title'")).uniq },
      query: -> { query.where(Arel.sql("answers->>'title' = '#{filter_param.value}'")) }
    }

    field :description, filterable: {
      type: :select,
      options: -> { Feedback.pluck(Arel.sql("answers->>'description'")).uniq },
      query: -> { query.where(Arel.sql("answers->>'description' = '#{filter_param.value}'")) }
    }
  end
end
```

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

### Creating Resources (POST)

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/index.md

This section details how to create new resources using the API. It covers the request format, provides examples for basic creation and creation with associations, and outlines success and error responses.

```APIDOC
## Creating Resources (POST)

### Request Format

To create a new resource, send a POST request with the field data in the request body. The API supports nested parameter format.

```bash
POST /api/resources/v1/teams
Content-Type: application/json

{
  "team": {
    "name": "New Development Team",
    "url": "https://dev.newteam.com",
    "description": "A newly formed development team"
  }
}
```

### Examples

**Basic Creation:**

```bash
curl -X POST /api/resources/v1/teams \
  -H "Content-Type: application/json" \
  -d '{
    "team": {
      "name": "Mobile Team",
      "url": "https://mobile.company.com"
    }
  }'
```

**With Associations:**

```bash
curl -X POST /api/resources/v1/teams \
  -H "Content-Type: application/json" \
  -d '{
    "team": {
      "name": "Backend Team",
      "url": "https://backend.company.com",
      "admin_id": 5
    }
  }'
```

### Response (Success - 201 Created)

```json
{
  "record": {
    "id": 3,
    "name": "Mobile Team",
    "url": "https://mobile.company.com",
    "description": null,
    "admin": null
  }
}
```

### Response (Error - 422 Unprocessable Entity)

```json
{
  "errors": {
    "name": ["can't be blank"],
    "url": ["is not a valid URL"]
  },
  "message": "Failed to create Team"
}
```

### Field Types

Different field types accept different data formats:

**Text/String Fields:**

```json
{
  "name": "Team Name",
  "description": "Team description"
}
```

**Number Fields:**

```json
{
  "count": 42,
  "price": 19.99
}
```

**Boolean Fields:**

```json
{
  "active": true,
  "featured": false
}
```

**Date/DateTime Fields:**

```json
{
  "created_at": "2024-01-15T10:30:00Z",
  "start_date": "2024-01-15"
}
```

**Belongs To Associations:**

```json
{
  "admin_id": 5,
  "category_id": 2
}
```
```

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

### Grid Item Badge - Complete Example

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/grid-view.md

Display and customize a badge on grid items. This example shows dynamic badge configuration based on record status, including label, color, style, title, and icon.

```ruby
# Dynamic badge based on record status
self.grid_view = {
  card: -> do
    {
      cover_url: record.image.attached? ? main_app.url_for(record.image.variant(resize_to_fill: [300, 300])) : nil,
      title: record.title,
      body: simple_format(record.description),
      badge: {
        label: record.new? ? "New" : "Updated",
        color: record.new? ? "green" : "orange",
        style: record.new? ? "solid" : "subtle",
        title: record.new? ? "New product available" : "Recently updated",
        icon: record.new? ? "heroicons/outline/arrow-trending-up" : "heroicons/outline/arrow-path"
      }
    }
  end
}
```

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

### Configure Main Menu in Initializer

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/menu-editor.md

Add the `main_menu` key to your `config/initializers/avo.rb` file to customize the sidebar. This example shows how to create sections, groups, resources, and links with icons and active states.

```ruby
Avo.configure do |config|
  config.main_menu = -> {
    section "Resources", icon: "tabler/outline/building-store", collapsable: false do
      group "Company", collapsable: true do
        resource :projects do
          link "First project", active: :inclusive, path: "/admin/resources/projects/1"
          link "Second project", active: :inclusive, path: "/admin/resources/projects/2"
        end
        resource :team, icon: "heroicons/outline/user-group"
        resource :team_membership
        resource :reviews, icon: "heroicons/outline/star"
      end
    end

    section I18n.t('avo.other'), icon: "heroicons/outline/finger-print", collapsable: true, collapsed: true do
      link_to 'Avo HQ', path: 'https://avohq.io', target: :_blank
      link_to 'Jumpstart Rails', path: 'https://jumpstartrails.com/', target: :_blank
    end
  }
end
```

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

### Define Comment Policy

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authorization.md

Example of defining an edit policy for comments.

```ruby
class CommentPolicy
  # ... more policy methods
  def edit
    record.user_id == current_user.id
  end
end
```

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

### Enable ViewComponent Instrumentation

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/views-performance.md

Add this configuration to your `application.rb` or `development.rb` file to enable performance tracking for ViewComponents.

```ruby
config.view_component.instrumentation_enabled = true
```

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

### Add Avo Forms Gem

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/forms-and-pages/overview.md

Add the avo-forms gem to your Gemfile and run bundle install.

```ruby
gem "avo-forms", source: "https://packager.dev/avo-hq/"

```

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

### Pill Shaped Button

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/native-components/avo-button-component.md

Example of creating a pill-shaped button using the `rounded: :full` option.

```erb
<%= a_button(rounded: :full) { "Pill" } %>
```

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

### Configure Persistence Driver

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/customization.md

Enable persistence for UI state like pagination and filters by setting the persistence driver. The default driver is nil, meaning no persistence is applied.

```ruby
Avo.configure do |config|
  config.persistence = {
    driver: :session
  }

  # Or with a dynamic block

  config.persistence = -> do
    {
      driver: :session
    }
  end
end
```

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

### Metric Card with Formatting

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/cards.md

Example of a MetricCard using `self.format` to apply custom formatting to the displayed result.

```ruby
class Avo::Cards::AmountRaised < Avo::Cards::MetricCard
  self.id = "amount_raised"
  self.label = "Amount raised"
  self.prefix = "$"
  self.format = -> {
    number_to_social value, start_at: 1_000
  }

  def query
    result 9001
  end
end
```

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

### Metric Card without Formatting

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/cards.md

Example of a basic MetricCard implementation without any custom data formatting.

```ruby
class Avo::Cards::AmountRaised < Avo::Cards::MetricCard
  self.id = "amount_raised"
  self.label = "Amount raised"
  self.prefix = "$"

  def query
    result 9001
  end
end
```

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

### Create New Rails App with Avo Pro

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/common/technical-support.md

Run this command to create a new Rails application with the Avo Pro version installed. Useful for testing Pro features or setting up a Pro-based reproduction.

```bash
rails new -m https://avo.cool/new-pro.rb APP_NAME
```

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

### Add Media Library to Main Menu

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/media-library.md

Integrate the Media Library into the main Avo menu by using the `media_library` helper within the `config.main_menu` lambda.

```ruby
Avo.configure do |config|
  config.main_menu = lambda {
    link_to 'Media Library', avo.media_library_index_path
  }
end
```

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

### Install Avo Notifications Gem

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/notifications.md

Add the avo-notifications gem to your Gemfile. Ensure you are using the correct source for the gem.

```ruby
gem "avo-notifications", source: "https://packager.dev/avo-hq/"

```

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

### Install Avo with Bullet Train Template

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/installation.md

Apply this template to integrate Avo into an existing Bullet Train application.

```ruby
bin/rails app:template LOCATION=https://v3.avohq.io/templates/bullet-train.template
```

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

### Define Section with Groups and Resources

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/menu-editor.md

This example shows how to create a top-level section with a name and icon, containing multiple groups. Each group can be collapsable and optionally collapsed by default, and they contain nested resources.

```ruby
section "Resources", icon: "heroicons/outline/academic-cap" do
  group "Academia", collapsable: true do
    resource :course
    resource :course_link
  end

  group "Blog", collapsable: true, collapsed: true do
    resource :posts
    resource :comments
  end
end
```

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

### Configure ProgressBarField Options

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/custom-fields.md

Shows how to initialize the ProgressBarField with custom options for max, step, display_value, and value_suffix, and how to use it in a resource.

```ruby
# app/avo/fields/progress_bar_field.rb
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
  attr_reader :max
  attr_reader :step
  attr_reader :display_value
  attr_reader :value_suffix

  def initialize(name, **args, &block)
    super(name, **args, &block)

    @max = args[:max] || 100
    @step = args[:step] || 1
    @display_value = args[:display_value] || false
    @value_suffix = args[:value_suffix] || nil
  end
end

# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
  self.title = :name

  def fields
    field :id, as: :id, link_to_record: true
    field :progress, as: :progress_bar, step: 10, display_value: true, value_suffix: "%"
  end
end
```

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

### Auto-generated Avo Controller File

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/resources.md

This is an example of an auto-generated Avo Controller file. It should always accompany an Avo Resource.

```ruby
# app/controllers/avo/cars_controller.rb
class Avo::CarsController < Avo::ResourcesController
end
```

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

### Prompt for Avo Resource Generation with Gemini

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/common/llm-support/gemini-common.md

This example demonstrates how to combine the 'Deep research' feature with a specific prompt to create an Avo resource for a product model.

```text
🔍 Deep research create an Avo resource for a product model
```

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

### Generate Application Controller

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/common/application_controller_eject_notice.md

Use this command to generate the `app/controllers/avo/application_controller.rb` file if it's missing from your application.

```bash
rails generate avo:eject --controller application_controller
```

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

### Link with Method and Data Attributes

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/native-components/avo-button-component.md

Example of rendering a link that uses `method: :delete` and `data` attributes for confirmation.

```erb
<%= a_link("/posts/1", method: :delete, data: { turbo_confirm: "Are you sure?" }) do %>
  Delete
<% end %>
```

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

### Icon-Only Button with Tight Padding

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/native-components/avo-button-component.md

Example of an icon-only button with tightened padding using the `padding: :sm` option.

```erb
<%= a_button(padding: :sm, icon: "tabler/outline/dots") %>
```

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

### Configure Home Path and Initial Breadcrumbs

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/customization.md

Set both the `home_path` and `set_initial_breadcrumbs` to create a cohesive navigation experience, especially when customizing the home path.

```ruby
Avo.configure do |config|
  config.home_path = "/avo/dashboard"
  config.set_initial_breadcrumbs do
    add_breadcrumb "Dashboard", "/avo/dashboard"
  end
end
```

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

### Override Generated Association Policy Method

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authorization.md

Example of overriding a generated policy method to provide custom logic.

```ruby
inherit_association_from_policy :comments, CommentPolicy

def destroy_comments?
  false
end
```

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

### Create a Reusable Form with Panels and Fields

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/forms-and-pages/forms.md

Create a reusable form with fields grouped into cards and panels. This example demonstrates setting default values, placeholders, and help text, and persisting form data in the `handle` method.

```ruby
class Avo::Forms::AppSettings < Avo::Forms::Core::Form
  self.title = "Application Settings"
  self.description = "Configure global application settings"

  def fields
    card do
      field :app_name, as: :text,
            default: -> { Rails.application.class.module_parent_name },
            required: true
      field :app_url, as: :text, placeholder: "https://yourapp.com"
      field :maintenance_mode, as: :boolean, default: false
    end

    panel title: "Feature Flags" do
      field :enable_registrations, as: :boolean, default: true
      field :max_file_upload_size, as: :number, default: 10, help_text: "In MB"
    end
  end

  def handle
    ApplicationSettings.update_all(
      params.permit(:app_name, :app_url, :maintenance_mode,
                    :enable_registrations, :max_file_upload_size)
    )

    flash[:success] = { body: "Application settings updated", timeout: 5000 }
    default_response
  end
end
```

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

### Define Post Policy with Comment Edit Access

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authorization.md

Example of a post policy that inherits edit access for comments.

```ruby
class PostPolicy
  # ... more policy methods
  def edit_comments?
    Pundit.policy!(user, record).edit?
  end
end
```

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

### Docker Build Command with Gem Server Token

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/gem-server-authentication.md

Build a Docker image using the docker build command, passing the BUNDLE_PACKAGER__DEV token as a build argument. Alternatively, set the environment variable on your machine and pass it.

```bash
docker build --build-arg BUNDLE_PACKAGER__DEV=xxx
```

```bash
# Set the key as an environment variable on your machine
# Somewhere in your `.bashrc` or `.bash_profile` file
export BUNDLE_PACKAGER__DEV=xxx
# Then pass it to the build argument from there
docker build --build-arg BUNDLE_PACKAGER__DEV=$BUNDLE_PACKAGER__DEV
```

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

### Reload Multiple Records (Array Input)

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/actions/execution.md

Example of using `reload_records` with an array of records to refresh their state in the UI.

```ruby
reload_records([record_1, record_2])
```

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

### Docker Build with Gem Server Token Argument

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/gem-server-authentication.md

Build a Docker image by passing the BUNDLE_PACKAGER__DEV token as a build argument. This makes the token available within the Docker image for bundle install.

```dockerfile
ARG BUNDLE_PACKAGER__DEV
ENV BUNDLE_PACKAGER__DEV=$BUNDLE_PACKAGER__DEV
```

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

### Basic Setup for Mounting Avo API

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/rest-api/mount.md

This code snippet shows the basic configuration in `config/routes.rb` to mount the Avo API within a Rails application.

```APIDOC
## Basic Setup

```ruby
# config/routes.rb
Rails.application.routes.draw do
  devise_for :users

  # Mount Avo API
  mount_avo_api

  # Mount Avo
  authenticate :user do
    mount_avo do
      get "tool_with_form", to: "tools#tool_with_form", as: :tool_with_form
    end
  end

  # Redirect to Avo root path
  root to: redirect(Avo.configuration.root_path)
end
```
```

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

### Customize Current User Resource Name (Admin Example)

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/authentication.md

Set the `current_user_resource_name` to `:current_admin` if your logout path is `destroy_current_admin_session_path`.

```ruby
Avo.configure do |config|
  config.current_user_resource_name = :current_admin
end
```

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

### Troubleshoot File Not Found Warning

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/README-vitepress-llms-concatenator.md

Handle 'File not found' warnings by checking the existence of linked files in your documentation or by updating the sidebar configuration to reflect the correct file paths.

```bash
Warning: File not found: docs/4.0/missing-file.md
```

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

### Count Unread Notifications

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/notifications.md

Get the count of unread notifications for a user, which is used to drive the bell badge indicator.

```ruby
# Count unread notifications (drives the bell badge)
Avo::Notifications.unread_count(user)
```

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

### Avo License Validation Payload

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/licensing.md

This is the payload sent to the Avo HQ for license validation. It includes details about your Avo installation.

```ruby
# HQ ping payload
{
  license: Avo.configuration.license,
  license_key: Avo.configuration.license_key,
  avo_version: Avo::VERSION,
  rails_version: Rails::VERSION::STRING,
  ruby_version: RUBY_VERSION,
  environment: Rails.env,
  ip: current_request.ip,
  host: current_request.host,
  port: current_request.port,
  app_name: Rails.application.class.to_s.split("::").first,
  avo_metadata: avo_metadata
}
```

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

### Handle Form Submission with Various Flash Messages

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/forms-and-pages/forms.md

This example shows how to set different types of flash messages (notice, error, success, warning) before returning a default response. The success and warning messages demonstrate custom bodies and timeout configurations.

```ruby
def handle
  flash[:notice] = "Operation completed successfully"
  flash[:error] = "Something went wrong"
  flash[:success] = { body: "Saved successfully", timeout: 3000 }
  flash[:warning] = { body: "Heads up", timeout: :forever }

  default_response
end
```

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

### Using Multiple `all_` Helpers in Avo Menu

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/4.0/menu-editor.md

This snippet demonstrates how to use `all_dashboards`, `all_resources`, and `all_tools` helpers within different groups inside a section to populate the Avo menu dynamically. Ensure authorization rules are set for `all_resources`.

```ruby
section "App", icon: "heroicons/outline/beaker" do
  group "Dashboards" do
    all_dashboards
  end

  group "Resources" do
    all_resources
  end

  group "All tools" do
    all_tools
  end
end
```

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

### Create New Rails App with Avo

Source: https://github.com/avo-hq/docs.avohq.io/blob/main/docs/common/technical-support.md

Use this command to generate a new Rails application with Avo pre-installed. This is a quick way to set up a project for testing or reproduction.

```bash
rails new -m https://avo.cool/new.rb APP_NAME
```