### Bedrock Documentation Website Setup

Source: https://github.com/maacck/bedrock-py/blob/main/README.md

Instructions to set up and run the documentation website locally. This involves navigating to the docs directory, installing dependencies, and starting the development server.

```bash
cd docs-web
pnpm install
pnpm dev
```

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

### Install All Modules

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Example of how to install all modules within the Bedrock application.

```bash
bedrock manage install
```

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

### Example: Auth Module Quick Start

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/playbooks.mdx

Demonstrates how to import and use the authentication service for logging in users and checking permissions. Ensure necessary entities and services are imported.

```python
from myapp.auth import auth_service
from myapp.auth.entities import UserEntity

# Login
user = auth_service.authenticate(email="alice@example.com", password="secret")

# Check permissions
if auth_service.has_permission(user, "users:write"):
    ...
```

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

### Initial Project Setup with Bedrock CLI

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Use these commands to install the Bedrock application, verify module information, and check the database status.

```bash
# 1. Install the application
bedrock manage install

# 2. Verify modules
bedrock app info myapp.users
bedrock app info myapp.products

# 3. Check database status
bedrock db current myapp.users
```

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

### Example Installation Output

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Shows the expected output when a Bedrock application is successfully installed.

```bash
✓ Installing application...
Installing app: myapp.users 0.1.0
✓ Schema created (tables initialised and stamped at head).
Running pre-install hook for myapp.users...
Running post-install hook for myapp.users...
✓ Application installed successfully.
```

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

### Install Specific Module

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Example of how to install a specific module, such as 'myapp.users', using the '-A' option.

```bash
bedrock manage install -A myapp.users
```

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

### Initialize New Project with Bedrock CLI

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/bedrock-cli/index.mdx

Guides through the initial setup of a new project using the Bedrock CLI, including initializing the project, syncing dependencies, adding the first submodule, and scaffolding a domain module.

```bash
# 1. Initialize project
bedrock-cli init my-project
cd my-project
uv sync

# 2. Add your first submodule
bedrock-cli add submodule users src/my_project --bootstrap

# 3. Add a domain module (blank scaffold)
bedrock-cli add domain profile src/my_project/users

# 4. After defining models, generate typed code
bedrock-cli gen entity my_project.users.models:User src/my_project/users/user
bedrock-cli gen service my_project.users.models:User src/my_project/users/user
```

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

### Example Playbook Content for Storage Module

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/playbooks.mdx

This markdown example illustrates the content of a playbook generated by `bedrock app playbook mycompany.storage`. It provides AI agents with a quick start guide, API usage examples, and backend configuration details.

```markdown
# Storage Module

## Quick Start
from mycompany.storage import storage_service, StorageSettings

# Upload a file
url = storage_service.upload(
    path="avatars/user-123.jpg",
    content=file_bytes,
    content_type="image/jpeg",
)

## Backends
- S3: Set STORAGE_BACKEND=s3, STORAGE_S3_BUCKET=my-bucket
- Local: Set STORAGE_BACKEND=local, STORAGE_LOCAL_PATH=./uploads

```

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

### Install and Populate Modules

Source: https://github.com/maacck/bedrock-py/blob/main/README.md

Demonstrates how to install a module by name and then populate the registry, which runs on_load hooks for all modules. Ensure the ModuleRegistry is imported.

```python
from bedrock.module.registry import ModuleRegistry

apps = ModuleRegistry()
apps.install("inventory")  # Validates dependencies, loads in order
apps.populate()            # Runs on_load hooks for all modules
```

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

### Example: Running Module Commands

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/cli-guide.md

Demonstrates invoking 'create-user' and 'list-users' commands from the 'myapp.users' module.

```bash
bedrock run --app myapp.users create-user --name Alice --email alice@example.com
```

```bash
bedrock run --app myapp.users list-users
```

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

### Install Skipping Migrations

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Example of how to install the Bedrock application while skipping database migrations using the '--skip-migrations' option.

```bash
bedrock manage install --skip-migrations
```

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

### Install and Set Up Pre-commit Hooks

Source: https://github.com/maacck/bedrock-py/blob/main/CONTRIBUTING.md

Install the pre-commit package and set up the project's pre-commit hooks for automated checks.

```bash
pip install pre-commit
pre-commit install
```

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

### Bedrock Module Bootstrap Hooks Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-guide.md

Demonstrates the implementation of `on_load`, `ready`, and `on_shutdown` hooks. The `on_load` hook is used for early initialization and dependency checks. The `ready` hook is for configuring services and starting background tasks after all modules are installed. The `on_shutdown` hook is for cleanup operations.

```python
def on_load(*, registry, app) -> None:
    """Called during module installation."""
    if not registry.is_installed("myproject.core"):
        raise RuntimeError("myproject.core must be installed first")

```

```python
def ready(*, registry, app, container, hooks) -> None:
    """Called after all modules are installed."""
    from .service import user_service
    user_service.initialize()
    # Register services in the DI container
    container.register(IUserRepo, factory=UserRepo, lifetime=Lifetime.SINGLETON)

```

```python
def on_shutdown(*, registry, app) -> None:
    """Called during shutdown."""
    from .service import user_service
    user_service.cleanup()

```

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

### Install and Populate Modules

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/overview.mdx

Installs a module, validates its dependencies, and loads it into the registry. Then, it populates the registry and marks modules as ready by running their respective hooks.

```python
from bedrock.module.registry import ModuleRegistry

apps = ModuleRegistry()
apps.install("inventory")  # Validates dependencies, loads in order
apps.populate()            # Runs on_load hooks
apps.mark_ready()          # Runs ready hooks
```

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

### Install Bedrock Core from GitHub with uv

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Install bedrock-core directly from its GitHub repository using uv, specifying a subdirectory.

```bash
uv add "bedrock-core @ git+https://github.com/maacck/bedrock-py#subdirectory=packages/bedrock"
```

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

### Install Bedrock CLI with uv

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Install the bedrock-cli scaffolding tool directly from GitHub using uv.

```bash
uv add "bedrock-cli @ git+https://github.com/maacck/bedrock-py#subdirectory=packages/bedrock-cli"
```

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

### Install Bedrock Core

Source: https://github.com/maacck/bedrock-py/blob/main/packages/bedrock/README.md

Install the bedrock-core package using uv, poetry, or pip.

```bash
# With uv (recommended)
uv add bedrock-core

# With poetry
poetry add bedrock-core

# With pip
pip install bedrock-core
```

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

### Install Bedrock from Source

Source: https://github.com/maacck/bedrock-py/blob/main/README.md

Clone the repository and install from source for local development using uv. This ensures all packages within the workspace are synchronized.

```bash
git clone https://github.com/maacck/bedrock-py.git
cd bedrock-py
uv sync --all-packages
```

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

### Initialize Project and Install Bedrock

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Commands to create a new project directory, initialize it, and add bedrock-core using uv.

```bash
mkdir my-project && cd my-project
uv init
uv add bedrock-core
```

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

### Install a Bedrock Module

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/cli-scripts.md

Installs a module by running database migrations and executing installation hooks. You can specify the module to install or skip migrations.

```bash
bedrock manage install [options]
```

```bash
bedrock manage install
```

```bash
bedrock manage install -A myapp.users
```

```bash
bedrock manage install -A myapp.users --skip-migrations
```

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

### Develop Documentation Site

Source: https://github.com/maacck/bedrock-py/blob/main/AGENTS.md

Starts a development server for the Starlight documentation site with live synchronization.

```bash
cd starlight-docs && npm run dev
```

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

### Setup Project with uv

Source: https://github.com/maacck/bedrock-py/blob/main/AGENTS.md

Synchronizes all packages within the project using the uv package manager.

```bash
uv sync --all-packages
```

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

### Install Bedrock with Redis Cache Extra using uv

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Install bedrock-core with the optional cache-redis dependency group using uv.

```bash
uv add bedrock-core[cache-redis]
```

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

### Example Full Directory Structure

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-hierarchy.mdx

Shows a project with submodules and domain modules, highlighting the organizational convention.

```text
my_app/
├── __init__.py
├── settings.py
├── oms/
│   ├── __init__.py
│   ├── manifest.yaml
│   ├── bootstrap.py
│   ├── sales_order/             # Domain Module
│   │   ├── __init__.py
│   │   ├── entities.py
│   │   └── service.py
│   └── purchase_order/          # Domain Module
│       ├── __init__.py
│       ├── entities.py
│       └── service.py
└── auth/
    ├── __init__.py
    ├── manifest.yaml
    └── ...

```

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

### Define Installation Hooks

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-guide.md

Implement pre_install, install, and post_install functions in an installation.py file to customize the Bedrock application installation process. The install hook is suitable for seeding data after migrations.

```python
from bedrock.database import db


def pre_install() -> None:
    """Run before database migrations."""
    print("Preparing installation...")


def install() -> None:
    """Run after migrations — seed data, etc."""
    from .models import UserModel
    with db.session as session:
        if not session.query(UserModel).first():
            session.add(UserModel(name="admin", email="admin@example.com", hashed_password="..."))
            session.commit()

def post_install() -> None:
    """Run after install — final checks."""
    print("Installation complete!")
```

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

### Install a Bedrock Module

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/cli-guide.md

Installs a module, including running database migrations and executing installation hooks. You can specify a module or use the BEDROCK_APP environment variable.

```bash
bedrock manage install
```

```bash
bedrock manage install -A myapp.users
```

```bash
bedrock manage install -A myapp.users --skip-migrations
```

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

### Example Project Directory Structure

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-hierarchy.mdx

Illustrates a top-level project directory containing submodules.

```text
erp/
├── __init__.py
├── settings.py
├── oms/                         # Submodule
│   └── ...
└── auth/                        # Submodule
    └── ...

```

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

### Playbook CLI Examples

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/playbooks.mdx

These examples demonstrate how to use the 'bedrock app playbook' command to access different types of playbook files within a module.

```bash
# Examples
bedrock app playbook myapp.auth
bedrock app playbook myapp.auth references/api-reference.md
bedrock app playbook myapp.auth examples/login-flow.py
```

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

### Install Bedrock Application

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Installs the current Bedrock application. Options allow specifying a particular module to install or skipping database migrations.

```bash
bedrock manage install [OPTIONS]
```

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

### List Available Module Commands

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Example of how to list all available commands for a specific module by using the '--help' flag.

```bash
bedrock run --app myapp.users --help
```

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

### Quick Start: Register and Resolve a Service

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/di.mdx

Demonstrates the basic usage of registering a service with a singleton lifetime and resolving it for use. Ensure bedrock.di is imported.

```python
from bedrock.di import Lifetime, container


class Mailer:
    def send(self, to: str, subject: str, body: str) -> None:
        print(to, subject)


container.register(Mailer, factory=Mailer, lifetime=Lifetime.SINGLETON)

mailer = container.resolve(Mailer)
mailer.send("alice@example.com", "Welcome", "Hello")
```

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

### Example Output for Uninstall

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

This shows the confirmation message after successfully uninstalling all migrations for an application.

```bash
$ bedrock db uninstall myapp.users

✓ myapp.users downgraded to base. You can now remove it from INSTALLED_APPS.
```

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

### Next Steps After Project Initialization

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/bedrock-cli/index.mdx

After scaffolding a new project, navigate into the project directory and synchronize dependencies using `uv sync`. You can then start adding submodules to your project.

```bash
cd my-saas-app
uv sync
# Start adding submodules:
bedrock-cli add submodule users src/my_saas_app
```

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

### Install and Access Bedrock Module

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-anatomy.mdx

This Python snippet demonstrates how to install a module using apps.populate and access it via apps.get. It shows how to retrieve the module's manifest title.

```python
from bedrock.module.registry import apps

# Install and ready the module
apps.populate(["my_module"])

# Access the module
module = apps.get("my_module")
print(module.manifest.title)  # "My Module"
```

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

### Install Dependencies with uv

Source: https://github.com/maacck/bedrock-py/blob/main/CONTRIBUTING.md

Synchronize and install project dependencies using the uv package manager.

```bash
uv sync
```

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

### Quick Start: Create, Connect, and Send a Signal

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/signals.mdx

Demonstrates the basic workflow of creating a signal, connecting a receiver function, and sending the signal with associated data.

```python
from bedrock.signal import Signal

# 1. Create a signal
order_placed = Signal("Emitted when an order is placed")

# 2. Connect a receiver
def notify_warehouse(sender, **kwargs):
    print(f"New order from {sender}: {kwargs['order_id']}")

order_placed.connect(notify_warehouse)

# 3. Send the signal
order_placed.send(current_app, order_id="ORD-001")
# Output: New order from <App>: ORD-001
```

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

### Install Bedrock CLI with pip

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Install the bedrock-cli scaffolding tool directly from GitHub using pip.

```bash
pip install "git+https://github.com/maacck/bedrock-py#subdirectory=packages/bedrock-cli"
```

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

### Run Development Server

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/README.md

Commands to start the Next.js development server using npm, pnpm, or yarn.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

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

### Install Bedrock Core with pip

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Use this command to install the bedrock-core package using pip.

```bash
pip install bedrock-core
```

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

### Initialize Bedrock Application

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/SKILL.md

Sets up the Bedrock application by specifying the main module path. This should be called once at the start of the process.

```python
import bedrock

bedrock.setup("myproject.modules.users")
```

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

### Initialize Bedrock Runtime and Access Singletons

Source: https://github.com/maacck/bedrock-py/blob/main/README.md

Basic usage example demonstrating how to initialize the Bedrock runtime and access key singleton components like the ModuleRegistry and DatabaseManager.

```python
import bedrock

# Initialize the runtime (discovers and loads modules)
bedrock.setup()

# Access key singletons
from bedrock.module import apps          # ModuleRegistry
from bedrock.database import db          # DatabaseManager
```

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

### Submodule Manifest Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-hierarchy.md

Example manifest.yaml for a Bedrock submodule, defining its title, description, version, and dependencies.

```yaml
# oms/manifest.yaml
title: Order Management System
description: Handles orders, fulfillment, and returns
version: 0.1.0
depends_on:
  - my_app.auth
commands: "commands:app"
```

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

### Bedrock Module Structure Example

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/agent-skills.mdx

Illustrates the standard file organization for a Bedrock application module.

```text
my_app/
└── my_module/
    ├── __init__.py
    ├── manifest.yaml
    ├── models.py
    ├── entities.py
    ├── service.py
    ├── exc.py
    └── bootstrap.py
```

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

### Project Package Marker

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-hierarchy.md

Example of an empty __init__.py file for a project that is a plain Python package.

```python
# my_app/__init__.py — just a package marker, no lifecycle hooks
```

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

### Install Bedrock Core with uv

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Use this command to add the bedrock-core package to your project using uv.

```bash
uv add bedrock-core
```

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

### Bedrock Module Manifest Schema Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-guide.md

An example of a manifest.yaml file, defining module metadata such as title, version, description, dependencies, and CLI commands.

```yaml
title: User Management
version: "0.1.0"
description: User authentication and profile management
depends_on:
  - myproject.core
commands: commands:app
```

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

### Install Bedrock Core with poetry

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Add the bedrock-core package to your project using poetry.

```bash
poetry add bedrock-core
```

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

### Bedrock Manifest.yaml Example

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/agent-skills.mdx

Shows the structure and required fields for a `manifest.yaml` file in a Bedrock module.

```yaml
title: my_module
description: Module description
version: 0.1.0
depends_on:
  - other_module
commands: "commands:app"
```

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

### Install Bedrock Agent Skill

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/agent-skills.mdx

Install the Bedrock agent skill using npx to teach your AI assistant about Bedrock conventions and patterns.

```bash
npx skills add https://github.com/maacck/bedrock-py
```

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

### Create Initial Migration Revision

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

This example shows how to create the very first migration revision for an application, which establishes the branch root.

```bash
# First revision (creates branch root)
bedrock db revision myapp.users -m "initial schema"
```

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

### Example Submodule Manifest

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-hierarchy.mdx

Defines a submodule's metadata, description, version, and dependencies.

```yaml
title: Order Management System
description: Handles orders, fulfillment, and returns
version: 0.1.0
depends_on:
  - my_app.auth
commands: "commands:app"

```

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

### Bedrock Hook: Call/Response Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/signals-guide.md

Use hooks for extension points where implementations contribute behavior or return values. This example demonstrates defining a hook specification with `firstresult=True` and implementing it with priority.

```python
from bedrock.hooks import HookNamespace
auth = HookNamespace("auth")

@auth.spec(firstresult=True)
def authenticate(request):
    """Return user if authenticated, None otherwise."""

@auth.impl(priority=10)
def check_token(request):
    if valid_token(request.token):
        return get_user_from_token(request.token)
    return None  # Let next impl try

request = Request(token="...")
results = auth.call("authenticate", request=request)
user = results[0] if results else None
```

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

### Execute Specific Module Command

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Example of running the 'create-user' command for the 'myapp.users' module, providing 'name' and 'email' arguments.

```bash
bedrock run --app myapp.users create-user --name Alice --email alice@example.com
```

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

### Project Directory Structure Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-hierarchy.md

Illustrates the typical directory layout for a Bedrock project, including submodules and domain modules.

```text
my_app/                          # Project
├── __init__.py
├── settings.py
├── oms/                         # Submodule
│   ├── __init__.py
│   ├── manifest.yaml
│   ├── bootstrap.py
│   ├── sales_order/             # Domain Module
│   │   ├── __init__.py
│   │   ├── entities.py
│   │   └── service.py
│   └── purchase_order/          # Domain Module
│       ├── __init__.py
│       ├── entities.py
│       └── service.py
└── auth/                        # Submodule
    ├── __init__.py
    ├── manifest.yaml
    └── ...

```

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

### Module Manifest Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/SKILL.md

A basic manifest.yaml file for a Bedrock module, specifying its title, version, and description.

```yaml
title: User Management
version: "0.1.0"
description: User authentication and profiles
```

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

### Quick Start: Payment Hooks

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/hooks.mdx

Demonstrates defining a hook namespace, a hook spec with firstresult=True, an implementation, adding implementations, and calling the hook.

```python
from bedrock.hooks import HookNamespace

payment_hooks = HookNamespace("payment")


@payment_hooks.spec(firstresult=True)
def process(method: str, amount: int) -> str | None:
    ...


class CardHooks:
    @payment_hooks.impl(priority=0)
    def process(self, method: str, amount: int) -> str | None:
        if method == "card":
            return "charged"
        return None


payment_hooks.add_impls_from(CardHooks(), module="card_gateway")


result = payment_hooks.call("process", method="card", amount=100)
assert result == ["charged"]
```

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

### Example Cross-Project Dependency Declaration

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-hierarchy.mdx

Demonstrates how a separate project can declare dependencies on submodules from another project.

```text
my_app_worker/
├── __init__.py
├── manifest.yaml               # depends_on: ["my_app.oms", "my_app.auth"]
└── ...

```

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

### Verify Bedrock Installation with Python

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

A simple Python script to verify that the Bedrock library is imported correctly.

```python
import bedrock

print(bedrock)
```

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

### Module Service Implementation

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-anatomy.mdx

The service.py file contains the business logic for the module. This example defines a GreetingService that produces greeting messages.

```python
from .entities import Greeting


class GreetingService:
    """Service that produces greetings."""

    def greet(self, name: str) -> Greeting:
        """Create a greeting for the given name."""
        return Greeting(message=f"Hello, {name}!", recipient=name)
```

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

### Create Subsequent Migration Revision

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

This example demonstrates creating a new migration revision for an existing application branch.

```bash
# Subsequent revision
bedrock db revision myapp.users -m "add email verification"
```

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

### Bedrock CLI Commands for Module Invocation

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-guide.md

Examples of how to run Bedrock CLI commands to invoke module-specific applications and commands.

```bash
bedrock run --app myproject.modules.users create-user --name Alice --email alice@example.com
```

```bash
bedrock run --app myproject.modules.users list-users
```

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

### Bedrock CLI: Module Management

Source: https://github.com/maacck/bedrock-py/blob/main/README.md

Commands for inspecting, getting info about, and installing modules within a Bedrock application. Use these to validate manifests and manage module lifecycle.

```bash
bedrock app inspect <module>   # Validate manifest and bootstrap
```

```bash
bedrock app info <module>      # Display module details
```

```bash
bedrock app install <module>   # Run migrations and hooks
```

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

### Bedrock CLI Commands for Module Management

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/overview.mdx

Use these commands to inspect, get information about, and install modules within your Bedrock application. Ensure the module name is correctly specified.

```bash
# Module management
bedrock app inspect <module>   # Validate manifest
bedrock app info <module>      # Display module details
bedrock app install <module>   # Run migrations and hooks
```

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

### Override Service Template Example

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/bedrock-cli/custom-templates.mdx

This Jinja2 template shows how to override the default service template for Bedrock CLI. It includes asynchronous functions for getting, creating, and deleting entities using SQLAlchemy.

```jinja
{# _bedrock_gen/service.py.j2 #}
from __future__ import annotations

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from ..models import {{ model_name }}


async def aget(session: AsyncSession, pk: int) -> {{ model_name }} | None:
    return await session.get({{ model_name }}, pk)


async def acreate(session: AsyncSession, **kwargs) -> {{ model_name }}:
    instance = {{ model_name }}(**kwargs)
    session.add(instance)
    await session.flush()
    return instance


async def adelete(session: AsyncSession, instance: {{ model_name }}) -> None:
    await session.delete(instance)
    await session.flush()

```

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

### Create and List User CLI Commands

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-guide.md

Defines Typer commands for creating and listing users, including Bedrock setup and service imports.

```python
import typer
import bedrock

app = typer.Typer(name="users", help="User management commands")


@app.command()
def create_user(name: str, email: str) -> None:
    """Create a new user."""
    bedrock.setup()
    from .service import user_service
    from .entities import UserCreateRequest
    user = user_service.create_user(UserCreateRequest(name=name, email=email, password="temp"))
    typer.echo(f"Created user: {user.name} ({user.email})")


@app.command()
def list_users() -> None:
    """List all users."""
    bedrock.setup()
    from .service import user_service
    users = user_service.list_users()
    for user in users:
        typer.echo(f"  {user.name} (<{user.email}>)")
```

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

### Module Manifest Registration

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

Example YAML snippet showing how to register a module's commands in the 'manifest.yaml' file, linking the 'commands:app' entry.

```yaml
title: User Management
version: "0.1.0"
commands: commands:app
```

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

### Add Submodule to Existing Project

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/bedrock-cli/index.mdx

Illustrates the process of adding a new submodule to an existing project, including bootstrapping and installation flags, and then adding domain modules within that submodule.

```bash
# Add submodule skeleton
bedrock-cli add submodule billing src/my_project --bootstrap --installation

# Add domain modules within it
bedrock-cli add domain invoice src/my_project/billing
bedrock-cli add domain payment src/my_project/billing

# Generate entities and service from models
bedrock-cli gen entity my_project.billing.models:Invoice src/my_project/billing/invoice
bedrock-cli gen service my_project.billing.models:Invoice src/my_project/billing/invoice
```

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

### Verify Bedrock Installation

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Command to check the installed Bedrock version.

```bash
bedrock -v
```

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

### Bedrock Filter Specification Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/SKILL.md

Example of a simple filter specification for database queries.

```json
{"field": "name", "op": "==", "value": "Alice"}
```

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

### Create Module Directory Structure

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/tutorial.mdx

Set up the basic directory and initialization file for a new Bedrock module.

```bash
mkdir -p inventory
touch inventory/__init__.py
```

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

### Bedrock OR Filter Specification Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/SKILL.md

Example of an OR filter specification for database queries, combining multiple conditions.

```json
{"or": [{"field": "age", "op": ">", "value": 30}, {"field": "name", "op": "==", "value": "Bob"}]}
```

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

### Creating a Basic Signal

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/signals.mdx

Illustrates how to instantiate the base `Signal` class, optionally providing a docstring for descriptive purposes.

```python
from bedrock.signal import Signal

user_created = Signal("Emitted after a new user is persisted")
payment_failed = Signal()  # No docstring
```

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

### Registering Services in a Custom Container

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/di-guide.md

Demonstrates creating a custom container and registering both a class as a singleton and a pre-built instance.

```python
from bedrock.di import Container, Lifetime

custom = Container()
custom.register(InventoryService, factory=InventoryService, lifetime=Lifetime.SINGLETON)
custom.register_instance("app.config", {"region": "sandbox"})
```

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

### Bedrock Initialization Sequence

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/architecture.md

Details the step-by-step process for initializing Bedrock components during application startup.

```text
import time → apps exists (empty), db exists (unconfigured), container exists, hooks exists
    ↓
bedrock.setup() → apps.populate(module_list)
    ↓
on_load hooks → modules call db.init(url) if needed
    ↓
apps.mark_ready() → ready hooks fire
    ↓
hooks.validate() → warn about orphaned impls or empty specs
    ↓
registry_ready signal emitted
```

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

### Create, Update, and Delete a Product Instance

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/database.mdx

Demonstrates creating a new product instance, updating its attributes using the .update() method, and deleting it from the session.

```python
# Create and use
product = Product(name="Widget", price=999)
product.dict()  # {"id": None, "name": "Widget", "price": 999}

# Update attributes
product.update(price=1499)

# Delete (must be attached to a session)
session.add(product)
session.commit()
product.delete()
session.commit()
```

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

### Module Initialization File

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-anatomy.mdx

The __init__.py file serves as the main entry point for the module and contains its docstring.

```python
"""My Module — a minimal Bedrock module."""
```

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

### Bedrock Signal: Notification Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/signals-guide.md

Use signals for simple notifications where return values are not needed. This example shows how to define a signal, connect a receiver function, and send the signal.

```python
from bedrock.signal import Signal
user_created = Signal("user_created")

@user_created.connect
def on_user_created(sender, **kwargs):
    send_welcome_email(kwargs["user"])  # Fire-and-forget

user_created.send(sender, user=new_user)
```

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

### Registering a Pre-built Instance

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/di.mdx

Illustrates how to register an already existing object instance under a specific string key. This is useful for configuration objects or shared resources.

```python
from bedrock.di import container

config = {"region": "ap-southeast-1"}
container.register_instance("app.config", config)
```

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

### Domain Module Import Example

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-hierarchy.md

How to import a function from a domain module within a submodule.

```python
from my_app.oms.sales_order.service import create_order
```

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

### Create Basic main.py for Bedrock Runtime

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

A minimal Python script to bootstrap the Bedrock runtime and check loaded modules.

```python
import bedrock

bedrock.setup()

apps = bedrock.apps
print(f"Registry ready with {len(apps.modules)} module(s) loaded")
```

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

### Build All Packages

Source: https://github.com/maacck/bedrock-py/blob/main/AGENTS.md

Builds all packages in the monorepo using uv.

```bash
uv build --all-packages
```

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

### Create and Use a Cache Namespace

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cache.mdx

Demonstrates how to create a cache namespace, build keys within it, list keys, and clear the namespace. Requires importing the cache module.

```python
from bedrock.contrib.cache import cache

# Create a namespace
users = cache.namespace("users")

# Build keys within the namespace
key = users.build_key("user", "123")  # "users:user:123"

# List all keys in the namespace
all_user_keys = users.list(limit=50)

# Clear all keys in the namespace
count = users.clear()
```

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

### Bedrock CLI Overview

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cli.mdx

The general structure for using the Bedrock CLI.

```bash
bedrock [OPTIONS] COMMAND [ARGS]
```

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

### DatabaseManager Initialization

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/database.mdx

Initializes the database engine and session factory. This method should be called once at the start of the process.

```APIDOC
## db.init()

### Description
Initializes the SQLAlchemy engine and session factory for the database manager. This is a crucial setup step that should be performed once when the application process begins.

### Method
`init(url: str | None = None, settings: DbSettings | None = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
None

### Error Handling
Accessing database properties before calling `init()` will raise `DatabaseNotConfiguredError`.
```

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

### Scaffold a new Bedrock project

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock-cli/SKILL.md

Use `bedrock-cli init` to create a new Bedrock project. Navigate into the project directory and synchronize dependencies.

```bash
bedrock-cli init my-saas-app
cd my-saas-app
uv sync
```

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

### Check GitHub CLI Version

Source: https://github.com/maacck/bedrock-py/blob/main/docs/agents/issue-tracker.md

Verify that the GitHub CLI is installed and available on your system's PATH.

```bash
gh --version
```

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

### Build Production Documentation

Source: https://github.com/maacck/bedrock-py/blob/main/AGENTS.md

Builds the production version of the Starlight documentation site.

```bash
cd starlight-docs && npm run build
```

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

### Initialize a New Bedrock Project

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/bedrock-cli/index.mdx

Use `bedrock-cli init` to create a new Bedrock project. Specify the project name and optionally an output directory. The command scaffolds a standard project structure with essential configuration files.

```bash
bedrock-cli init <name> [OPTIONS]
```

```bash
$ bedrock-cli init my-saas-app

ℹ Creating project my-saas-app at my-saas-app
✓ my-saas-app/pyproject.toml
✓ my-saas-app/.python-version
✓ my-saas-app/README.md
✓ my-saas-app/src/my_saas_app/__init__.py
✓ my-saas-app/src/my_saas_app/manifest.yaml
✓ my-saas-app/src/my_saas_app/models.py
✓ my-saas-app/src/my_saas_app/bootstrap.py
✓ my-saas-app/src/my_saas_app/installation.py
✓ my-saas-app/src/my_saas_app/exc.py

ℹ Next steps:
ℹ   cd my-saas-app
ℹ   uv sync
```

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

### Cross-Project Dependency Manifest

Source: https://github.com/maacck/bedrock-py/blob/main/skills/bedrock/references/module-hierarchy.md

Example manifest.yaml for a worker project demonstrating cross-project dependencies using 'depends_on'.

```yaml
# my_app_worker/manifest.yaml
title: Background Worker
version: 0.1.0
depends_on:
  - my_app.oms
  - my_app.auth

```

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

### Synchronous Hook Calls

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/hooks.mdx

Example of making a synchronous call to a hook specification to retrieve results from implementations.

```python
results = auth_hooks.call("get_permissions", user_id="user-1")
```

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

### Create Module Manifest File

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/tutorial.mdx

Define the module's metadata and command entry point in the `manifest.yaml` file.

```yaml
title: inventory
description: Product inventory management
version: 0.1.0
commands: "commands:app"
```

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

### Register and Configure Custom Cache Backend

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cache.mdx

Demonstrates how to register a custom cache backend class and then configure the cache to use it. The custom backend must implement the required methods from `CacheBackend`.

```python
from bedrock.contrib.cache import register_backend, CacheBackend

class MyCustomBackend(CacheBackend):
    # Implement required methods...
    pass

register_backend("custom", MyCustomBackend)
cache.configure("custom")
```

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

### Get Inventory Module Details

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/tutorial.mdx

Retrieves detailed information about the inventory module using the Bedrock CLI.

```bash
bedrock app info inventory
```

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

### Inspect a Module with Bedrock CLI

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/installation.mdx

Command to get information about a specific Bedrock module using the CLI.

```bash
bedrock app info <module_name>
```

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

### Google-Style Docstring Example

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/getting-started/contributing.mdx

Use Google-style docstrings for all public functions, classes, and methods to ensure clear documentation.

```python
def get_user(user_id: int) -> User:
    """Retrieve a user by their ID.

    Args:
        user_id: The unique identifier of the user.

    Returns:
        The user instance.

    Raises:
        UserNotFoundError: If no user exists with the given ID.
    """
    
```

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

### Basic Cache Operations (Set and Get)

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/cache.mdx

Demonstrates how to store and retrieve values using the cache. Includes synchronous and asynchronous methods. Values are automatically configured with an in-memory backend by default.

```python
from bedrock.contrib.cache import cache

# Store a value (auto-configures with in-memory backend)
cache.set("user:123", {"name": "Alice"}, ex=300)

# Retrieve it
user = cache.get("user:123")
print(user)  # {"name": "Alice"}

# Async variants
await cache.aset("user:456", {"name": "Bob"}, ex=600)
user = await cache.aget("user:456")
```

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

### Module Exception Definition

Source: https://github.com/maacck/bedrock-py/blob/main/docs-web/content/docs/en/(bedrock)/guides/module-anatomy.mdx

The exc.py file defines custom exceptions for the module, inheriting from BedrockExc. This example defines a GreetingError.

```python
from bedrock.exc import BedrockExc


class GreetingError(BedrockExc):
    """Raised when a greeting cannot be produced."""

    detail = "Failed to produce greeting"
```