Learning Path

From Beginner to Advanced (Step by Step)

This is the detailed learning route. Follow stages in order. Each stage has goals, commands, and completion criteria.

Stage 0: Environment and install check

mosaic --version
mosaic --help
mosaic --project-state directory --ensure --check-writable

Done when CLI runs and state directory is writable.

Stage 1: First provider setup

export OPENAI_API_KEY=<your_key>

mosaic --project-state --profile default setup \
  --base-url https://api.openai.com \
  --api-key-env OPENAI_API_KEY \
  --model gpt-4o-mini

Done when setup exits successfully and config file is created.

Stage 2: Connectivity and model baseline

mosaic --project-state --profile default models list
mosaic --project-state --profile default models status
mosaic --project-state --profile default health
mosaic --project-state --profile default status

Done when models list returns models and health shows no blocking error.

Stage 3: First interaction workflow

mosaic --project-state --profile default ask "hello"
mosaic --project-state --profile default chat

mosaic --project-state session list
mosaic --project-state session show <session_id>

Done when one ask and one chat session are both recorded.

Stage 4: Multi-profile (Azure example)

export AZURE_OPENAI_BASE_URL="https://<resource>.openai.azure.com/openai/v1"
export AZURE_OPENAI_API_KEY="<your_key>"

mosaic --project-state --profile az-openai setup \
  --base-url "$AZURE_OPENAI_BASE_URL" \
  --api-key-env AZURE_OPENAI_API_KEY \
  --model gpt-4o-mini

mosaic --project-state --profile az-openai models list

Done when each profile can independently list models.

Deep dive: Models & Profiles.

Stage 5: Channels and notifications

mosaic --project-state channels add --name local-terminal --kind terminal
mosaic --project-state channels list
mosaic --project-state channels test <channel_id>
mosaic --project-state channels send <channel_id> --text "stage-5-ok"

Done when test and send both succeed for at least one channel.

Deep dive: Channels Guide.

Stage 6: Gateway lifecycle

mosaic --project-state gateway install --host 127.0.0.1 --port 8787
mosaic --project-state gateway start
mosaic --project-state gateway status
mosaic --project-state gateway probe
mosaic --project-state gateway call status

Done when probe and call return successful status.

Deep dives: Gateway Guide and Gateway Call API.

Stage 7: Safety policy and guardrails

mosaic --project-state approvals get
mosaic --project-state approvals set confirm
mosaic --project-state approvals allowlist add "git status"

mosaic --project-state sandbox get
mosaic --project-state sandbox set standard
mosaic --project-state sandbox explain --profile standard

Done when approvals/sandbox both match your intended policy.

Deep dive: Approvals & Sandbox Policy.

Stage 8: Daily observability

mosaic --project-state dashboard
mosaic --project-state doctor
mosaic --project-state logs --tail 120
mosaic --project-state system presence

Done when dashboard and doctor outputs are clean enough for daily operations.

Keep session hygiene: Sessions Guide.

Stage 9: Agents module (start here)

mosaic --project-state agents list
mosaic --project-state agents add --name Writer --id writer --set-default --route ask --route chat
mosaic --project-state agents show writer
mosaic --project-state ask --agent writer "summarize this repo"

Done when a custom agent can be created and used in ask/chat.

Stage 10: Advanced checks and release gate

mosaic --project-state memory index --path .
mosaic --project-state knowledge ingest --source local_md --path docs --namespace knowledge --incremental
mosaic --project-state knowledge search "retry" --namespace knowledge
mosaic --project-state security audit --path . --deep
mosaic --project-state --json status

• Core commands available: setup/models/ask/chat/session.
• Main channel and gateway both healthy.
• Policy and diagnostics output are stable.
• --json output is script-parseable.

Runbook: Regression Guide.