### Install Gems and Run Setup Scripts

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Install Ruby gems and then run the application's configuration and setup scripts to prepare the development environment.

```bash
bundle install
bin/configure
bin/setup
```

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

### Start PostgreSQL Service

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

If Homebrew is installing PostgreSQL for the first time, use this command to start the PostgreSQL service.

```bash
brew services start postgresql@14
```

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

### Start Redis Service

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

If Homebrew is installing Redis for the first time, use this command to start the Redis service.

```bash
brew services start redis
```

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

### Run Bullet Train Setup Script

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Execute the setup script to prepare the development environment.

```bash
bin/setup
```

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

### Clone and Bootstrap a New Bullet Train Application

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Follow these steps to clone the starter template, install dependencies, and boot the development server. Ensure Homebrew, rbenv, and nvm are installed and configured correctly before proceeding.

```bash
# 1. Clone the starter template
git clone https://github.com/bullet-train-co/bullet_train.git my_app
cd my_app

# 2. Install Homebrew dependencies (macOS) — Ruby, Node, Postgres, Redis, etc.
brew bundle

# 3. Activate the correct Ruby version
rbenv init
rbenv install $(cat .ruby-version)
# Open a new shell tab before continuing

# 4. Activate the correct Node version
source ~/.zshrc
nvm install
corepack enable

# 5. Install Ruby and JS dependencies, rename the project, set up GitHub, etc.
bundle install
bin/configure       # Interactive: renames "Untitled Application", sets up git remotes
bin/setup           # Creates & migrates the database, builds assets, checks all dependencies

# 6. Boot
bin/dev             # Starts Rails, esbuild, PostCSS via Overmind
# Visit http://localhost:3000
```

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

### Run Insight Setup Script

Source: https://github.com/bullet-train-co/bullet_train/blob/main/test/system/super_scaffolding/README.md

Execute the setup script to generate scaffolding and run migrations for the Insight test. Ensure you are in the main project directory.

```bash
$ ./test/system/super_scaffolding/insight/setup.rb
Generating Insight model with 'bin/rails generate model Insight team:references name:string description:text'

Writing './app/controllers/account/insights_controller.rb'.
Fixing Standard Ruby on './app/controllers/account/insights_controller.rb'.
Writing './app/views/account/insights/index.html.erb'.
Writing './app/views/account/insights/_menu_item.html.erb'.
# snip
```

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

### Docker Compose Development Setup

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Commands for setting up and running Bullet Train in a development environment using Docker Compose. This includes building the image, creating the database, and starting all services.

```bash
# Development with Docker Compose (bin/docker-dev/)
bin/docker-dev/build
bin/docker-dev/create   # sets up DB
bin/docker-dev/start    # boots all services
bin/docker-dev/shell    # open a shell inside the container
```

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

### Initialize and Configure rbenv

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

If Homebrew is installing rbenv for the first time, run these commands to initialize rbenv and install the Ruby version specified in .ruby-version. A new shell session is required afterward.

```bash
rbenv init
rbenv install `cat .ruby-version`
```

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

### Boot Development Server

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Start the local development server for your Bullet Train application. Access it via http://localhost:3000.

```bash
bin/dev
```

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

### API Controller Test Example

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

An example of an API controller test in Ruby, demonstrating how to verify CRUD operations and cross-user access denial for team resources. It uses FactoryBot for data setup.

```ruby
# test/controllers/api/v1/teams_controller_test.rb
require "controllers/api/v1/test"

class Api::V1::TeamsControllerTest < Api::Test
  setup do
    @teams = create_list(:team, 3)        # FactoryBot — belong to @user's team
    @team.save
    @another_team = create(:team)         # belongs to a different user
  end

  test "index" do
    get "/api/v1/teams", params: {access_token: access_token}
    assert_response :success

    ids = response.parsed_body.map { |t| t["id"] }
    assert_includes ids, @team.id           # own teams returned
    assert_not_includes ids, @another_team.id  # other users' teams hidden
    assert_proper_object_serialization response.parsed_body.first
  end

  test "show — cross-user access denied" do
    get "/api/v1/teams/#{@team.id}", params: {access_token: another_access_token}
    assert_response :not_found             # 404 not 403 to avoid information leakage
  end

  test "update" do
    put "/api/v1/teams/#{@team.id}", params: {
      access_token: access_token,
      team: {name: "New Name", time_zone: "UTC", locale: "fr"}
    }
    assert_response :success
    assert_equal "New Name", @team.reload.name
  end
end
```

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

### Install Dependencies with Homebrew Bundle (macOS)

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

On macOS, this command installs all project dependencies using Homebrew. Additional manual configuration may be required for nvm and rbenv.

```bash
brew bundle
```

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

### Configure Node.js Environment

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Source your shell configuration, install the Node.js version managed by nvm, and enable Corepack for package manager support.

```bash
source ~/.zshrc
nvm install
corepack enable
```

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

### Configure nvm Environment Variables

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Add these lines to your ~/.zshrc file if Homebrew is installing nvm for the first time. This ensures nvm is correctly sourced in your shell.

```bash
mkdir ~/.nvm
touch ~/.zshrc
open ~/.zshrc
```

```bash
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"
```

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

### Render Deployment Configuration

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Instructions for deploying a Bullet Train application on Render, including environment variable setup. Render reads render.yaml for service definitions.

```bash
# One-click deploy button provisions web service + Postgres + Redis on Render.
# Render reads render.yaml for service definitions.
# The build script is bin/render-build.sh:
#   bundle install
#   yarn install
#   bundle exec rails assets:precompile
#   bundle exec rails db:migrate

# After provisioning, set required env vars in the Render dashboard:
#   BASE_URL      → https://your-app.onrender.com
#   RAILS_MASTER_KEY → (from config/master.key)
#   REDIS_URL     → (auto-populated by Render Redis add-on)
#   DATABASE_URL  → (auto-populated by Render Postgres add-on)
```

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

### Clone Bullet Train Template Repository

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Use this command to start a new project by cloning the Bullet Train template. Replace 'your_new_project_name' with your desired project name.

```bash
git clone https://github.com/bullet-train-co/bullet_train.git your_new_project_name
```

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

### Run Insight System Test

Source: https://github.com/bullet-train-co/bullet_train/blob/main/test/system/super_scaffolding/README.md

After setup, run the system test for the Insight feature using the rails test command. This will execute the tests in the specified directory.

```bash
$ rails test test/system/super_scaffolding/insight/
🌱 Generating global seeds.
🌱 Generating test environment seeds.
Not requiring Knapsack Pro.
If you'd like to use Knapsack Pro make sure that you've set the environment variable KNAPSACK_PRO_CI_NODE_INDEX
Started with run options --seed 45445

BulletTrain::SuperScaffolding::InsightTest
Puma starting in single mode...
* Puma version: 6.5.0 ("Sky's Version")
* Ruby version: ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [arm64-darwin23]
*  Min threads: 5
*  Max threads: 5
*  Environment: test
*          PID: 55207
* Listening on http://127.0.0.1:3001
Use Ctrl-C to stop
  test_developers_can_generate_a_Insight_and_a_nested_Personality::CharacterTrait_model PASS (3.51s)

Finished in 3.51351s
1 tests, 4 assertions, 0 failures, 0 errors, 0 skips
Coverage report generated for test to /Users/jgreen/projects/bullet-train-co/bullet_train/coverage.
Line Coverage: 45.18% (150 / 332)
```

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

### Bullet Train Application Environment Variables

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Configure essential application settings by copying the example file and filling in the required values. These variables control the base URL, marketing site redirection, and Stripe integration.

```yaml
# config/application.yml.example  (copy to config/application.yml and fill in values)
BASE_URL: http://localhost:3000        # Public base URL used in API OpenAPI spec and emails
MARKETING_SITE_URL: /account          # Root `/` redirect target; set to external marketing URL
# STRIPE_SECRET_KEY: sk_live_...      # Required if Stripe billing is enabled
```

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

### Get Authenticated User Profile

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve the profile information for the currently authenticated user. For OAuth2 platform agents, additional team details are included.

```bash
# List users visible to the token owner (typically just themselves)
curl https://your-app.com/api/v1/users \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Navigate to Project Directory

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

After cloning the repository, change into the newly created project directory.

```bash
cd your_new_project_name
```

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

### Create Provisioned Access Token

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Use this endpoint to create a new access token for server-to-server integrations. A description is required for the token.

```bash
curl -X POST https://your-app.com/api/v1/platform/applications/3/access_tokens \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform_access_token": {"description": "Zapier integration token"}}'
```

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

### Docker Production Build and Run

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Commands for building the production Docker image and running the Bullet Train application. Ensure all necessary environment variables are set.

```bash
# Build the production image
docker build -t my-app .

# Run using the production entrypoint (bin/docker/entrypoint)
docker run -e DATABASE_URL=postgres:// \
           -e REDIS_URL=redis:// \
           -e BASE_URL=https://my-app.com \
           -e RAILS_MASTER_KEY=... \
           -p 3000:3000 my-app
```

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

### Database Schema - Core Tables

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Highlights key tables created by migrations, including core multi-tenant tables, OAuth2/Platform API tables, and webhook-related tables.

```ruby
# db/schema.rb (condensed)

# Multi-tenant core
create_table "teams"        # name, slug, time_zone, locale, being_destroyed
create_table "users"        # Devise columns + first_name, last_name, time_zone, locale,
                            # profile_photo_id, ability_cache, OTP fields, lock fields
create_table "memberships"  # user_id, team_id, role_ids (jsonb), platform_agent,
                            # added_by_id, invitation_id, cached user name/email fields
create_table "invitations"  # email, uuid, from_membership_id, team_id, invitation_list_id

# OAuth2 / Platform API
create_table "oauth_applications"    # Doorkeeper apps scoped to a team
create_table "oauth_access_tokens"   # provisioned: bool distinguishes API keys from OAuth tokens
create_table "oauth_access_grants"   # short-lived authorization codes

# Webhooks
create_table "webhooks_outgoing_endpoints"        # url, name, event_type_ids (jsonb),
                                                  # api_version, webhook_secret,
                                                  # deactivated_at (auto-deactivated after failures)
create_table "webhooks_outgoing_events"           # uuid, event_type_id, payload (jsonb), team_id
create_table "webhooks_outgoing_deliveries"       # endpoint_id, event_id, delivered_at
create_table "webhooks_outgoing_delivery_attempts" # response_code, response_body, attempt_number
```

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

### Heroku Deployment Steps

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Steps for deploying a Bullet Train application on Heroku, including database migration, seeding, and scaling workers. This option provisions dyno, Postgres, Redis, and Sidekiq.

```bash
# One-click deploy button provisions dyno + Postgres + Redis + Sidekiq.
# After provisioning, run the documented post-deploy steps:
heroku run rails db:migrate --app your-app-name
heroku run rails db:seed --app your-app-name

# Scale workers for background jobs
heroku ps:scale worker=1 --app your-app-name
```

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

### Configure ngrok for Public URL

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Optional: Uncomment ngrok configuration in Procfile.dev and run this script to set BASE_URL to a publically accessible domain. Run again after restarting ngrok to update BASE_URL.

```bash
bin/set-ngrok-url
```

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

### Create Table Statements

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

These SQL statements are used for creating tables in the database for scaffolding demo resources.

```sql
create_table "scaffolding_absolutely_abstract_creative_concepts"      # team_id, name, description
```

```sql
create_table "scaffolding_completely_concrete_tangible_things"        # all field types
```

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

### Running a Single Controller Test

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Command to execute a specific controller test file. Useful for focused testing during development.

```bash
# Single controller test
bin/rails test test/controllers/api/v1/teams_controller_test.rb
```

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

### Create Team Invitation

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Send a new email invitation to a user to join a team. The response includes a UUID used for invitation links.

```bash
# Create a new invitation
curl -X POST https://your-app.com/api/v1/teams/1/invitations \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invitation": {"email": "newuser@example.com"}}'
```

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

### Running System Tests

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Command to run system tests, which typically use a browser automation tool like Selenium. The cuprite gem can be swapped in for Chrome DevTools integration.

```bash
# System tests (Selenium by default; swap in cuprite gem for Chrome DevTools)
bin/rails test:system
```

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

### Running the Full Test Suite

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Command to execute the entire test suite for the Bullet Train application. This is the standard way to ensure all tests pass.

```bash
# Full test suite
bin/rails test
```

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

### Running Parallel Tests

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Command for running tests in parallel, typically used in CI environments with tools like knapsack_pro. Specify the number of parallel processes.

```bash
# Parallel tests (used in CI with knapsack_pro)
bundle exec parallel_tests test/ -n 4
```

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

### Super Scaffolding

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Commands for generating new resources using the Super Scaffolding tool.

```APIDOC
## bin/rails generate super_scaffold [ResourceName] [ParentResource1],[ParentResource2] [field1:type] [field2:type] ...

### Description
Generates new resources, including models, migrations, controllers, views, API controllers, and more, based on the provided resource name, parent resources, and fields.

### Usage
```bash
# Scaffold a new resource "Project" nested under Team
bin/rails generate super_scaffold Project Team name:text_field description:text_area status:super_select{one}

# Scaffold a child resource "Task" under Project
bin/rails generate super_scaffold Task Project,Team title:text_field due_date:date_field completed:boolean
```

### Post-Generation Steps
- Run migrations after scaffolding:
  ```bash
  bin/rails db:migrate
  ```

### Generated Files
- `app/models/[resource_name].rb`
- `app/controllers/account/[resource_name]s_controller.rb`
- `app/controllers/api/v1/[resource_name]s_controller.rb`
- `app/views/api/v1/[resource_name]s/_[resource_name].json.jbuilder`
- `config/routes/api/v1.rb` (updates with new resource routes)
- `test/controllers/api/v1/[resource_name]s_controller_test.rb`
- `app/views/account/[resource_name]s/` (full CRUD UI views)
```

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

### Scaffold Child Resource with Super Scaffolding

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Generate a child resource (e.g., Task) nested under an existing resource (e.g., Project) and its parent (e.g., Team). Define fields with their types.

```bash
bin/rails generate super_scaffold Task Project,Team title:text_field due_date:date_field completed:boolean
```

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

### Scaffold New Resource with Super Scaffolding

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Generate a new resource (e.g., Project) with associated models, controllers, views, and API endpoints. Specify nested resources and field types.

```bash
bin/rails generate super_scaffold Project Team name:text_field description:text_area status:super_select{one}
```

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

### Run Migrations After Scaffolding

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Execute database migrations to apply the schema changes generated by Super Scaffolding. This command should be run after scaffolding new resources.

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

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

### List Platform Access Tokens

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve a list of Bearer tokens associated with a specific Platform::Application. Only provisioned tokens can be managed via this API.

```bash
# List access tokens for an OAuth application
curl https://your-app.com/api/v1/platform/applications/3/access_tokens \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Create Webhook Endpoint

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Set up a new outgoing webhook endpoint for a team, specifying the URL to receive events and the types of events to subscribe to. A `webhook_secret` is generated for payload verification.

```bash
curl -X POST https://your-app.com/api/v1/teams/1/webhooks/outgoing/endpoints \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks_outgoing_endpoint": {
      "name": "My Webhook",
      "url": "https://hooks.example.com/receive",
      "event_type_ids": ["invitation.created", "invitation.deleted"],
      "api_version": 1
    }
  }'
```

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

### List Team Memberships

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve a cursor-paginated list of all memberships for a given team. The `after` parameter is used for pagination.

```bash
# List all memberships on a team (cursor-paginated)
curl "https://your-app.com/api/v1/teams/1/memberships?after=0" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Set API Version

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Configure the current API version in the application's initializer. This ensures consistent API behavior.

```ruby
BulletTrain::Api.current_version = "v1"
```

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

### List Team Invitations

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve a list of pending invitations for a specific team. This endpoint does not support updates.

```bash
# List pending invitations for a team
curl https://your-app.com/api/v1/teams/1/invitations \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Exchange Code for Token

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Use this endpoint to exchange an authorization code for an access token. Ensure all parameters are correctly provided.

```bash
curl -X POST https://your-app.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "redirect_uri=CALLBACK_URL"
```

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

### Run Insight Teardown Script

Source: https://github.com/bullet-train-co/bullet_train/blob/main/test/system/super_scaffolding/README.md

After completing the tests, execute the teardown script to remove the super scaffolded code and revert database changes. This is a brute-force cleanup process.

```bash
$ ./test/system/super_scaffolding/insight/teardown.rb
db/schema.rb has changed - we need to rollback
== 20241219204101 CreatePersonalityCharacterTraits: reverting =================
-- drop_table(:personality_character_traits)
   -> 0.0037s
== 20241219204101 CreatePersonalityCharacterTraits: reverted (0.0073s) =========

== 20241219204056 CreateInsights: reverting ===================================
-- drop_table(:insights)
   -> 0.0016s
== 20241219204056 CreateInsights: reverted (0.0017s) ==========================

Updated 8 paths from the index

Removing app/avo/resources/insight.rb
Removing app/avo/resources/personality_character_trait.rb
Removing app/controllers/account/insights_controller.rb
Removing app/controllers/account/personality/
Removing app/controllers/api/v1/insights_controller.rb
Removing app/controllers/api/v1/personality/
Removing app/controllers/avo/insights_controller.rb
Removing app/controllers/avo/personality_character_traits_controller.rb
Removing app/models/insight.rb
Removing app/models/personality.rb
Removing app/models/personality/
Removing app/views/account/insights/
Removing app/views/account/personality/
Removing app/views/api/v1/insights/
Removing app/views/api/v1/personality/
Removing config/locales/en/insights.en.yml
Removing config/locales/en/personality/
Removing db/migrate/20241219204056_create_insights.rb
Removing db/migrate/20241219204101_create_personality_character_traits.rb
Removing test/controllers/api/v1/insights_controller_test.rb
Removing test/controllers/api/v1/personality/
Removing test/factories/insights.rb
Removing test/factories/personality/
Removing test/models/insight_test.rb
Removing test/models/personality/
```

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

### List Webhook Endpoints for a Team

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve a list of all configured outgoing webhook endpoints for a specific team. This helps in managing and monitoring webhook subscriptions.

```bash
curl https://your-app.com/api/v1/teams/1/webhooks/outgoing/endpoints \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Invitations API

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Create and manage email invitations for users to join a team.

```APIDOC
## GET /api/v1/teams/:team_id/invitations

### Description
Lists pending invitations for a specific team.

### Method
GET

### Endpoint
/api/v1/teams/:team_id/invitations

### Parameters
#### Path Parameters
- **team_id** (integer) - Required - The unique identifier of the team.
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the invitation.
- **email** (string) - The email address the invitation was sent to.
- **uuid** (string) - The unique identifier for the invitation, used in invitation links.
- **from_membership_id** (integer) - The ID of the membership that sent the invitation.
- **team_id** (integer) - The ID of the team the invitation is for.
- **created_at** (string) - Timestamp when the invitation was created.
- **updated_at** (string) - Timestamp when the invitation was last updated.

### Request Example
```bash
curl https://your-app.com/api/v1/teams/1/invitations \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

### Response Example
```json
[
  {
    "id": 5,
    "email": "bob@example.com",
    "uuid": "abc-123",
    "from_membership_id": 10,
    "team_id": 1,
    "created_at": "...",
    "updated_at": "..."
  }
]
```
```

```APIDOC
## POST /api/v1/teams/:team_id/invitations

### Description
Creates a new email invitation for a user to join a team.

### Method
POST

### Endpoint
/api/v1/teams/:team_id/invitations

### Parameters
#### Path Parameters
- **team_id** (integer) - Required - The unique identifier of the team to invite the user to.
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **invitation** (object) - Required - An object containing invitation details.
  - **email** (string) - Required - The email address of the user to invite.

### Response
#### Success Response (200)
- The created invitation JSON object, including its `uuid`.

### Request Example
```bash
curl -X POST https://your-app.com/api/v1/teams/1/invitations \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invitation": {"email": "newuser@example.com"}}'
```
```

```APIDOC
## DELETE /api/v1/invitations/:invitation_id

### Description
Revokes an existing invitation.

### Method
DELETE

### Endpoint
/api/v1/invitations/:invitation_id

### Parameters
#### Path Parameters
- **invitation_id** (integer) - Required - The unique identifier of the invitation to revoke.
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- Indicates successful revocation.

### Request Example
```bash
curl -X DELETE https://your-app.com/api/v1/invitations/5 \
  -H "Authorization: Bearer ACCESS_TOKEN"
```
```

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

### Declarative Role-Based Permissions

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Define roles and their associated model permissions in a YAML file. The `permit` helper in `Ability` automatically generates CanCanCan rules from this configuration.

```yaml
# config/models/roles.yml

# Every team member gets these baseline permissions
default:
  models:
    Team: read
    Membership:
      - read
      - search
    Invitation:
      - read
      - create
      - destroy
    Webhooks::Outgoing::Endpoint: manage
    Webhooks::Outgoing::Event: read

# "editor" role: can manage tangible things
editor:
  models:
    Scaffolding::CompletelyConcrete::TangibleThing: manage
    Scaffolding::AbsolutelyAbstract::CreativeConcept:
      - read
      - update

# "admin" role inherits editor + can manage the team itself
admin:
  includes:
    - editor
  manageable_roles:
    - admin
    - editor
  models:
    Team: manage
    Membership: manage
    Scaffolding::AbsolutelyAbstract::CreativeConcept: manage
    Platform::Application: manage
```

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

### List Teams

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve a list of all teams associated with the authenticated user. Requires an Authorization header with a Bearer token.

```bash
# List all teams for the authenticated user
curl https://your-app.com/api/v1/teams \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Fetch Specific User

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve the details of a specific user by their ID. The response may include team information for platform agents.

```bash
# Fetch a specific user
curl https://your-app.com/api/v1/users/42 \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Access Tokens API

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Endpoints for managing platform access tokens, including creation, updating descriptions, and revocation.

```APIDOC
## POST /api/v1/platform/applications/{application_id}/access_tokens

### Description
Creates a new provisioned access token for a given application. This is typically used for server-to-server integrations.

### Method
POST

### Endpoint
/api/v1/platform/applications/{application_id}/access_tokens

### Parameters
#### Path Parameters
- **application_id** (integer) - Required - The ID of the application for which to create the access token.

#### Request Body
- **platform_access_token** (object) - Required - Contains the details for the new access token.
  - **description** (string) - Optional - A description for the access token.

### Request Example
```json
{
  "platform_access_token": {
    "description": "Zapier integration token"
  }
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the created access token.
- **token** (string) - The generated access token.
- **description** (string) - The description of the access token.
- **application_id** (integer) - The ID of the application this token belongs to.

#### Response Example
```json
{
  "id": 7,
  "token": "ey...",
  "description": "Zapier integration token",
  "application_id": 3,
  "last_used_at": null
}
```
```

```APIDOC
## PUT /api/v1/platform/access_tokens/{access_token_id}

### Description
Updates the description of an existing access token.

### Method
PUT

### Endpoint
/api/v1/platform/access_tokens/{access_token_id}

### Parameters
#### Path Parameters
- **access_token_id** (integer) - Required - The ID of the access token to update.

#### Request Body
- **platform_access_token** (object) - Required - Contains the updated details for the access token.
  - **description** (string) - Required - The new description for the access token.

### Request Example
```json
{
  "platform_access_token": {
    "description": "Updated description"
  }
}
```
```

```APIDOC
## DELETE /api/v1/platform/access_tokens/{access_token_id}

### Description
Revokes an existing access token, making it invalid.

### Method
DELETE

### Endpoint
/api/v1/platform/access_tokens/{access_token_id}

### Parameters
#### Path Parameters
- **access_token_id** (integer) - Required - The ID of the access token to revoke.
```

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

### Define User Abilities with CanCan

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Defines user abilities based on roles and memberships. Reads roles from `roles.yml` automatically. Always-on individual user abilities are also defined.

```ruby
class Ability
  include CanCan::Ability
  include Roles::Permit

  def initialize(user)
    if user.present?
      # Reads roles.yml and inserts `can` calls for every membership the user has
      permit user, through: :memberships, parent: :team

      # Always-on individual user abilities
      can :manage, User, id: user.id
      can :read, User, id: user.collaborating_user_ids
      can :destroy, Membership, user_id: user.id
      can :manage, Invitation, id: user.teams.map(&:invitations).flatten.map(&:id)
      can :create, Team
      can :manage, Platform::AccessToken, application: {team_id: user.team_ids}, provisioned: true
    end
  end
end
```

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

### Devise User Model and Configuration

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Extend the User model to include custom validations and associations. Devise routes are automatically configured, providing standard paths for authentication and profile management.

```ruby
# app/models/user.rb — extend to add custom behavior
class User < ApplicationRecord
  include Users::Base    # Devise modules, profile photo, team associations, etc.
  include Roles::User    # Role helpers sourced from bullet_train-roles

  # Add custom validations, associations, scopes, or callbacks here:
  # validates :phone_number, presence: true
  # has_many :orders
end

# Devise routes are drawn from config/routes/devise.rb (via `draw "devise"` in routes.rb)
# Key paths (generated by Devise + Bullet Train):
#   GET  /users/sign_in         → sign-in form
#   POST /users/sign_in         → authenticate
#   GET  /users/sign_up         → registration form
#   POST /users                 → create user
#   GET  /users/password/new    → forgot-password form
#   PUT  /users/password        → reset password
#   GET  /account/users/:id/edit → edit profile (authenticated)

# Enabling invitation-only mode (config/initializers/bullet_train.rb):
BulletTrain.configure do |config|
  config.strong_passwords = !Rails.env.development?  # enforce complexity outside dev
  # config.enable_bulk_invitations = true             # allow bulk-invite CSV on onboarding
end
```

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

### Fetch Single Team

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Retrieve details for a specific team by its ID. Ensure the provided token has access to the team.

```bash
# Fetch a single team
curl https://your-app.com/api/v1/teams/1 \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Clone Bullet Train Repository

Source: https://github.com/bullet-train-co/bullet_train/blob/main/README.md

Clone your forked repository using the SSH path provided by GitHub.

```bash
git clone git@github.com:your-account/bullet_train.git
cd bullet_train
```

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

### Configure Outgoing Webhook Event Types

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Declare which models emit webhook events. The `crud` shorthand auto-generates `.created`, `.updated`, and `.deleted` event types.

```yaml
# config/models/webhooks/outgoing/event_types.yml
invitation:
  - crud       # generates: invitation.created, invitation.updated, invitation.deleted
membership:
  - crud
scaffolding/absolutely_abstract/creative_concept:
  - crud
scaffolding/completely_concrete/tangible_thing:
  - crud
```

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

### List Recent Webhook Events

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Fetch a list of recent outgoing webhook events for a team. This endpoint is read-only and useful for debugging or auditing webhook activity.

```bash
curl "https://your-app.com/api/v1/teams/1/webhooks/outgoing/events?after=0" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

### Define Avo User Resource

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Defines the User resource for the Avo admin panel. Specifies the title field, includes, and fields for display and interaction.

```ruby
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
  self.title = :full_name
  self.includes = []

  def fields
    field :id, as: :id
    field :email, as: :text
    field :first_name, as: :text
    field :last_name, as: :text
    field :time_zone, as: :select, options: -> {
      ActiveSupport::TimeZone.all.map {
        ["(GMT#{tz.formatted_offset}) #{tz.name}", tz.name]
      }.to_h
    }
    field :current_team, as: :belongs_to
    field :teams, as: :has_many, through: :teams
    field :memberships, as: :has_many
  end
end
```

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

### Update Access Token Description

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Modify the description of an existing access token using its ID. This is useful for updating the purpose or context of a token.

```bash
curl -X PUT https://your-app.com/api/v1/platform/access_tokens/7 \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform_access_token": {"description": "Updated description"}}'
```

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

### Platform Access Tokens API

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Manage Bearer tokens scoped to a Platform::Application (OAuth2 client).

```APIDOC
## GET /api/v1/platform/applications/:app_id/access_tokens

### Description
Lists all access tokens associated with a specific Platform Application.

### Method
GET

### Endpoint
/api/v1/platform/applications/:app_id/access_tokens

### Parameters
#### Path Parameters
- **app_id** (integer) - Required - The unique identifier of the Platform Application.
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
curl https://your-app.com/api/v1/platform/applications/3/access_tokens \
  -H "Authorization: Bearer ACCESS_TOKEN"
```
```

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

### Memberships API

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Manage which users belong to a team and what roles they hold.

```APIDOC
## GET /api/v1/teams/:team_id/memberships

### Description
Lists all memberships on a team, with cursor-based pagination.

### Method
GET

### Endpoint
/api/v1/teams/:team_id/memberships

### Parameters
#### Path Parameters
- **team_id** (integer) - Required - The unique identifier of the team.
#### Query Parameters
- **after** (integer) - Optional - The cursor for pagination, indicating the starting point for the next page of results.
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the membership.
- **user_id** (integer) - The ID of the user associated with the membership.
- **team_id** (integer) - The ID of the team the membership belongs to.
- **invitation_id** (integer) - The ID of the invitation, if the membership was created via an invitation.
- **user_first_name** (string) - The first name of the user.
- **user_last_name** (string) - The last name of the user.
- **user_profile_photo_id** (integer) - The ID of the user's profile photo.
- **user_email** (string) - The email address of the user.
- **added_by_id** (integer) - The ID of the user who added this membership.
- **platform_agent_of_id** (integer) - The ID of the platform this user is an agent of.
- **role_ids** (array of strings) - An array of role IDs assigned to the membership.
- **platform_agent** (boolean) - Indicates if the user is a platform agent.
- **created_at** (string) - Timestamp when the membership was created.
- **updated_at** (string) - Timestamp when the membership was last updated.

### Response Headers
- **Pagination-Next** (integer) - Use as the `after` parameter for the next page.
- **Link** (string) - Contains a link to the next page of results.

### Request Example
```bash
curl "https://your-app.com/api/v1/teams/1/memberships?after=0" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

### Response Example
```json
[
  {
    "id": 10,
    "user_id": 42,
    "team_id": 1,
    "invitation_id": null,
    "user_first_name": "Alice",
    "user_last_name": "Smith",
    "user_profile_photo_id": null,
    "user_email": "alice@example.com",
    "added_by_id": 7,
    "platform_agent_of_id": null,
    "role_ids": ["admin"],
    "platform_agent": false,
    "created_at": "...",
    "updated_at": "..."
  }
]
```
```

```APIDOC
## PUT /api/v1/memberships/:membership_id

### Description
Updates a membership, for example, to change a user's role within a team.

### Method
PUT

### Endpoint
/api/v1/memberships/:membership_id

### Parameters
#### Path Parameters
- **membership_id** (integer) - Required - The unique identifier of the membership to update.
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **membership** (object) - Required - An object containing the membership attributes to update.
  - **role_ids** (array of strings) - Required - An array of role IDs to assign to the membership.

### Response
#### Success Response (200)
- The updated membership JSON object.

### Request Example
```bash
curl -X PUT https://your-app.com/api/v1/memberships/10 \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"membership": {"role_ids": ["editor"]}}'
```
```

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

### Outgoing Webhooks API

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Endpoints for managing outgoing webhook endpoints and retrieving webhook events.

```APIDOC
## GET /api/v1/teams/{team_id}/webhooks/outgoing/endpoints

### Description
Lists all outgoing webhook endpoints configured for a specific team.

### Method
GET

### Endpoint
/api/v1/teams/{team_id}/webhooks/outgoing/endpoints

### Parameters
#### Path Parameters
- **team_id** (integer) - Required - The ID of the team whose webhook endpoints to list.
```

```APIDOC
## POST /api/v1/teams/{team_id}/webhooks/outgoing/endpoints

### Description
Creates a new outgoing webhook endpoint for a team, subscribing it to specified event types.

### Method
POST

### Endpoint
/api/v1/teams/{team_id}/webhooks/outgoing/endpoints

### Parameters
#### Path Parameters
- **team_id** (integer) - Required - The ID of the team for which to create the webhook endpoint.

#### Request Body
- **webhooks_outgoing_endpoint** (object) - Required - Contains the details for the new webhook endpoint.
  - **name** (string) - Required - The name of the webhook endpoint.
  - **url** (string) - Required - The URL where webhook payloads will be sent.
  - **event_type_ids** (array of strings) - Required - An array of event type IDs to subscribe to (e.g., "invitation.created").
  - **api_version** (integer) - Optional - The API version for the webhook.

### Request Example
```json
{
  "webhooks_outgoing_endpoint": {
    "name": "My Webhook",
    "url": "https://hooks.example.com/receive",
    "event_type_ids": ["invitation.created", "invitation.deleted"],
    "api_version": 1
  }
}
```

### Response
#### Success Response (200)
- **webhook_secret** (string) - A secret generated for the endpoint, used for HMAC signature verification.
```

```APIDOC
## GET "https://your-app.com/api/v1/teams/{team_id}/webhooks/outgoing/events?after=0"

### Description
Retrieves a list of recent outgoing webhook events for a specific team. This is a read-only operation.

### Method
GET

### Endpoint
/api/v1/teams/{team_id}/webhooks/outgoing/events

### Parameters
#### Path Parameters
- **team_id** (integer) - Required - The ID of the team whose webhook events to list.

#### Query Parameters
- **after** (integer) - Required - A cursor or timestamp to fetch events after a certain point. Example: "0".

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the webhook event.
- **uuid** (string) - A unique UUID for the event.
- **event_type_id** (string) - The type of the event (e.g., "membership.created").
- **team_id** (integer) - The ID of the team associated with the event.
- **api_version** (integer) - The API version of the event.
- **payload** (object) - The actual data payload of the event.
- **created_at** (string) - The timestamp when the event was created.

#### Response Example
```json
{
  "id": 99,
  "uuid": "evt_abc123",
  "event_type_id": "membership.created",
  "team_id": 1,
  "api_version": 1,
  "payload": { ... },
  "created_at": "..."
}
```
```

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

### OAuth2 Authorization Code Grant Flow Initiation

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Initiate the Authorization Code grant flow by redirecting the user to the OAuth2 authorization endpoint. This flow is used for user-facing OAuth2 applications.

```bash
# --- Authorization Code grant (user-facing OAuth2) ---
# Step 1: Redirect user to the authorization endpoint
# GET /oauth/authorize?client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&response_type=code
```

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

### OAuth Token Exchange

Source: https://context7.com/bullet-train-co/bullet_train/llms.txt

Exchange an authorization code for an access token using the OAuth2 protocol.

```APIDOC
## POST /oauth/token

### Description
Exchanges an authorization code for an access token.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be "authorization_code"
- **code** (string) - Required - The authorization code received from the authorization server.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
- **redirect_uri** (string) - Required - The redirect URI used in the initial authorization request.
```