[ML-70356] [m] Reorganize Agent Bricks getting-started docs

integrations/agentbricks/CONTRIBUTING.md

@@ -93,7 +93,7 @@ override):
 
 ```sh
 # local: the source uv resolved into the agent venv
-cat /tmp/scratch-agent/.venv/lib/python*/site-packages/databricks_agentkit-*.dist-info/direct_url.json
+cat /tmp/scratch-agent/.venv/lib/python*/site-packages/databricks_agentbricks-*.dist-info/direct_url.json
 # deployed: watch the build/install logs
 agentbricks deployments logs agent-bricks-<name>
 ```
@@ -154,6 +154,32 @@ the same change, in `src/databricks_agentbricks/cli/doctor.py`:
 Also refresh the framework references and examples in `cli.md` and `README.md`, and add doctor test
 coverage for the new framework in `tests/unit_tests/doctor_test.py`.
 
+## Live tool tests
+
+Read-only tool discovery can be checked against the installed wheel without creating a
+project or deploying an agent:
+
+```sh
+AGENTBRICKS_E2E_PROFILE=<profile> .venv-functional/bin/pytest tests/e2e/tool_discovery_test.py -v
+```
+
+The checks compare default and MCP-filtered discovery with the compatibility service
+list. Set `AGENTBRICKS_E2E_SCHEMA=catalog.schema` to exercise another schema. Local
+add/review/remove flows and help pages are covered by `tests/functional/cli_smoke_test.py`.
+
+The opt-in Genie tests exercise both frameworks against an existing Genie space. From
+`integrations/agentbricks`, with both framework extras installed:
+
+```sh
+DATABRICKS_CONFIG_PROFILE=my-workspace RUN_AGENTBRICKS_GENIE_TESTS=1 \
+  AGENTBRICKS_GENIE_SPACE_ID=SPACE_ID \
+  uv run pytest tests/integration_tests/genie_tools_test.py
+```
+
+By default they ask for the row count of `samples.nyctaxi.trips`. Set
+`AGENTBRICKS_GENIE_QUESTION` for another dataset and
+`AGENTBRICKS_GENIE_EXPECTED_VALUE` to assert a known result cell.
+
 ## Testing coding-agent skills
 
 The workflow skill is bundled under `src/databricks_agentbricks/templates/agent-bricks-workflow/`.

integrations/agentbricks/cli.md

@@ -22,7 +22,8 @@ pip install databricks-agentbricks
 
 The `databricks-agentbricks` distribution provides the `agentbricks` command and AgentKit SDK.
 
-See [Installation](README.md#installation) for installation details and shell completion.
+See [Installation](README.md#installation) for installation details and
+[Commands](README.md#commands) for shell completion.
 
 ## Authentication
 
@@ -1286,6 +1287,7 @@ Invoke arbitrary HTTP endpoints.
 #### `agentbricks endpoint invoke`
 
 Send one HTTP request to a Databricks App or arbitrary URL.
+Invoking a deployed App requires an OAuth-authenticated profile; PAT profiles are rejected.
 
 ```
 agentbricks endpoint invoke [APP] [options]

integrations/agentbricks/docs/coding-agent-skills.md

@@ -0,0 +1,41 @@
+# Coding-agent workflow skills
+
+The CLI bundles an `agent-bricks-workflow` skill for creating, developing, deploying, validating,
+and troubleshooting agents. It is separate from the project-specific `agent-bricks-migrate` skill
+generated by `init --existing`. Bundled guidance matches the installed CLI and requires no
+download or separate setup command.
+
+New `agentbricks init` projects already include the workflow skill. One shared bundle lives at
+`.agents/skills/agent-bricks-workflow/`; `.claude/skills/agent-bricks-workflow/` and
+`.agent/skills/agent-bricks-workflow/` contain pointers to it, not duplicate references.
+Migration discovery uses these same three roots. Installation is project-local, preserves unrelated
+configuration, leaves identical skills unchanged, and refuses to overwrite a different skill.
+
+Current coding agents discover these locations:
+
+| Coding agent | Project skill discovery |
+| --- | --- |
+| [Claude Code](https://code.claude.com/docs/en/skills) | `.claude/skills/` |
+| [Codex](https://developers.openai.com/codex/skills/) | `.agents/skills/` |
+| [Cursor](https://cursor.com/docs/skills) | `.agents/skills/` compatibility discovery |
+| [GitHub Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) | `.agents/skills/` |
+| [Gemini CLI](https://geminicli.com/docs/cli/skills/) | `.agents/skills/` compatibility discovery |
+| [OpenCode](https://opencode.ai/docs/skills/) | `.agents/skills/` compatibility discovery |
+| Other agents | Read the manifest directly |
+
+The `.agent/skills/` pointer retains the existing migration discovery location for agents using that
+convention. Support depends on the coding-agent version and its skill settings; restart the session
+if discovery is cached. Generated `AGENTS.md` also links to the workflow skill. The skill is
+advisory and does not authorize deployment or live calls.
+
+When the CLI detects a coding-agent environment, it emits a single-line pointer to the bundled
+skill on stderr, including for `--help`. Ordinary human invocations do not emit this hint.
+Coding agents in existing projects can read that bundled file directly without installing
+project-local skills or changing project configuration. Detection is best-effort and does not
+gate skill installation during `init` or native discovery. Set `AGENTBRICKS_DISABLE_AGENT_HINT=1`
+to suppress automatic hints. Hints never alter JSON stdout and are not emitted during shell
+completion, SDK imports, or deployed agent runtime startup.
+
+For a deployment-only task, local `dev` is optional. The workflow skill describes focused
+verification of the deployed agent, rather than treating local execution as proof of managed
+memory or session persistence.

integrations/agentbricks/docs/deploy-and-maintain.md

@@ -0,0 +1,125 @@
+# Deploy and manage a generated agent
+
+This guide is for owners of projects generated by `agentbricks init`. It explains which files and
+dependency inputs control a deployment, how application resources and agent state behave across local
+runs, redeployments, and deletion. For command syntax and options, see the [CLI command reference](../cli.md).
+To upgrade a customized scaffold, see [Upgrade a generated agent project](upgrading-generated-projects.md).
+
+## Deployment dependency inputs
+
+The generated `pyproject.toml` declares Python packages; `app.yaml` runs `uv run start-server` in
+Databricks Apps. Released packages can come from the configured package index (public PyPI by
+default, or `agentbricks deploy --pip-index-url <index-url>`). For the advanced case of deploying an
+unreleased package, pin a pushed Git commit that the Apps build can reach:
+
+```toml
+[tool.uv.sources]
+databricks-agentbricks = { git = "https://github.com/<you>/databricks-ai-bridge", rev = "<pushed-sha>", subdirectory = "integrations/agentbricks" }
+```
+
+Commit and push the ref before deploying; the Apps build clones that commit. A local path or
+`file://` source is unavailable inside the Apps build. Contributor-only local-path testing is
+documented in [CONTRIBUTING.md](../CONTRIBUTING.md#testing-sdk--runtime-changes-in-a-scaffold).
+
+`agentbricks deploy` uploads the project source but excludes the local `uv.lock`; the Apps build
+resolves dependencies against its own index. The generated `>=` requirements can therefore resolve
+to newer packages on a later deployment. Pin direct dependency versions in `pyproject.toml`, verify
+the selected package index and reachable Git commits, then compare the local environment with the
+deployed build logs. The current deploy flow does not provide a frozen transitive dependency graph
+from the local lockfile. Keep `agent.toml` bindings and the chosen app name alongside the dependency
+manifest so the same deployment targets the same managed resources.
+
+## Resource and state lifecycle
+
+The default managed-server template declares memory, session, and tracing names in `agent.toml`.
+`init` writes those declarations without creating workspace resources. `deploy` resolves them in the
+target workspace, creates missing resources, reuses accessible ones with matching names, creates or
+updates the App, rolls out the source, then attempts the App's store and trace access grants. An existing
+name that the caller cannot access causes an error. A grant failure can leave a deployed App without the
+corresponding feature; inspect deploy warnings.
+`agentbricks memory/sessions bind` and `unbind` edit `agent.toml`; they do not delete remote stores.
+For projects with `agent.toml`, the next deploy after a clean unbind removes the corresponding
+`AGENT_MEMORY_STORE`, `AGENT_SESSION_STORE`, or tracing setting from `app.yaml`. Unbinding does not
+revoke existing store grants; coordinate access removal separately with the store owner. A standalone
+source directory without `agent.toml` retains its manually configured environment settings.
+Default store names contain a six-letter token (`<name>-<token>-memory` and
+`<name>-<token>-sessions`); use `agentbricks memory bind <name>` or
+`agentbricks sessions bind <name>` to select existing stores. The default tracing experiment is
+under `/Shared/agentbricks_traces/`; `agentbricks tracing list` shows available traces.
+
+The Invocation Runtime Store row in the matrix applies only to projects with
+`[agent].server = "agentbricks"`. A custom server defines its own protocol and does not receive a
+managed Runtime Store.
+
+| Resource or state | Created or reused | Local `dev` and restart | Redeploy and cleanup |
+| --- | --- | --- | --- |
+| Project files and dependencies | `init` copies a template; `dev` builds `.venv` from `pyproject.toml`. | Source files stay on disk. The local environment is reused until `dev --prepare-environment` rebuilds it. | Deploy syncs source and resolves dependencies again without the local `uv.lock`. App deletion leaves the local project alone. |
+| Databricks App | Deploy creates the named App or reuses it, then updates compute and source. | `dev` serves the project locally without creating an App. | Redeploy with the same name updates that App; `agentbricks deployments delete <app-name>` deletes it. |
+| Invocation Runtime Store | The current default deploy creates or reuses an App-owned database in the workspace's shared Lakebase project. An internal legacy path uses a per-App Lakebase project. | `dev` keeps invocation status, results, and events in process; they disappear on restart. | Deployed invocation records persist across restart and redeploy. Queued work can resume; active work needs a recovery handler and may run more than once. `agentbricks deployments delete` removes the managed store before the App; the legacy delete path does not explicitly remove its Lakebase project. |
+| Managed tool access | Deploy reconciles direct App-auth tool grants from `agent.toml` before source upload, then finalizes Agent Bricks-owned App resources after rollout; request-user tools use the caller's permissions. | `dev` creates no App service principal or Apps grants. | Removing a tool binding removes Agent Bricks-owned Apps resources on redeploy. MCP grants are additive; see [automatic App-identity access](agent-tools.md#automatic-app-identity-access-on-deploy). |
+| Memory Store | Deploy creates a declared store if missing or reuses an accessible store by name, then attempts the App grant. | Managed long-term memory is off in `dev`. | Memory persists independently of the App; redeploy reuses the bound store. Unbinding or deleting the App does not delete it. Redeploy after unbind to detach the store, and use the separate store delete command when appropriate. |
+| Session Store | Deploy creates or reuses a declared store by name, then attempts the App grant. | `dev` keeps conversation state in process, so a restart loses it. | A bound store preserves LangGraph checkpoints and OpenAI Agents SDK transcripts across restart and redeploy. The current OpenAI harness also saves paused approval `RunState` separately from transcripts; see the release and adoption note below. Unbinding or deleting the App does not delete the store; redeploy after unbind to detach it. |
+| MLflow traces | `dev` uses a local MLflow server; deploy attempts to create or reuse the bound workspace experiment and grant App access. | Local traces are recorded in `.agentbricks/`; they remain on disk after `dev` stops. | Deployed traces remain in the workspace experiment. Unbinding removes the App's tracing configuration on a later clean deploy; it does not delete the experiment. |
+
+Redeploying an older App can attach the current managed Runtime Store without migrating invocation
+records from its legacy per-App Lakebase project. Managed-store cleanup errors retain the App for
+retry; deleting the App directly bypasses that cleanup.
+
+The Runtime Store tracks HTTP invocations, status, results, and event replay. The framework's
+conversation history belongs to its Session Store when bound. The generated chat UI keeps its
+session ID in browser local storage and sends that ID as the top-level `session_id` with each turn.
+`DurableAgentServer` accepts an optional top-level `session_id` for generic handlers, but the generated
+LangGraph and OpenAI Agents templates require a nonempty top-level `session_id` on every invocation.
+API clients should reuse that value for conversation continuity and send a new invocation `id` for each
+turn.
+By default, the templates use the session ID as the state actor; request-user-authenticated
+invocations namespace session state by user. LangGraph can resume from a matching checkpoint after
+worker loss; the OpenAI Agents SDK template replays the input against its saved transcript.
+Recovery can repeat external side effects, so make tools idempotent. For request-user-authenticated
+tools, credentials are not persisted and background recovery is unsupported.
+
+### OpenAI approval durability and upgrades
+
+On current `main`, the generated OpenAI harness saves paused SDK `RunState` in a separate Session
+Store checkpoint before emitting an interrupt. A bound Session Store preserves pending approvals
+across worker loss; concurrent workers also require a shared Runtime Store. Without a binding,
+pauses remain process-local. Clients must retain interrupt call IDs; transcript history alone does
+not reconstruct approval prompts.
+
+The harness validates decisions before changing state and persists a consumed marker before running
+accepted tools. Duplicate or recovered resumes cannot rerun an accepted approval. A failure after
+acceptance can leave uncertain side effects; inspect the invocation and tool outcome before starting
+a new ordinary turn. Other replayed work still requires idempotent tools. Request-user approvals
+remain unsupported.
+
+This harness fix landed after `databricks-agentbricks` 0.5.1 and is not included in that release.
+Existing projects own their copied harness: upgrading the package alone does not add checkpoint
+callbacks. Follow the [upgrade guide](upgrading-generated-projects.md) to adopt the updated
+`agent/agent.py`, `agent/checkpoints.py`, and `runtime/adapter.py` together from a compatible version.
+The [OpenAI integration contract](../src/databricks_agentbricks/templates/agent-openai/AGENTKIT_CONTRACT.md#recovery-and-durability)
+owns the detailed requirements.
+
+The default chat UI keeps its session ID across page reloads; see [invoke HTTP endpoints](../README.md#invoke-from-the-command-line)
+for the explicit API request shape.
+
+## Inspect and clean up a project
+
+Read `agent.toml` for the recorded agent name, declared memory/session stores, tracing, and tool
+bindings. A declaration does not confirm that the resource exists or that the deployed app can use it.
+
+| Inspect | Command | Details |
+| --- | --- | --- |
+| Local onboarding checks | `agentbricks doctor .` | Offline; does not verify bindings or deployed resources. |
+| Agent Bricks apps in a workspace | `agentbricks -p <profile> deployments list` | Lists apps with the `agent-bricks-` prefix in the selected workspace, including other projects. |
+| App status and URL | `agentbricks -p <profile> deployments get agent-bricks-<name>` | Queries the selected workspace for the named app. |
+| Memory store IDs and details | `agentbricks -p <profile> memory stores list`, then `agentbricks -p <profile> memory stores get <resource-name>` | Workspace-wide; can include other projects' stores. Use the ID or resource name, not the display name. |
+| Session store names and details | `agentbricks -p <profile> sessions stores list`, then `agentbricks -p <profile> sessions stores get <name>` | Workspace-wide; can include other projects' stores. Use the store name. |
+
+Review each confirmation. Delete a store only after confirming that you own it and no other agent
+needs it, using the same profile and identifier used to inspect it.
+
+| Clean up | Command | Details |
+| --- | --- | --- |
+| Deployment | `agentbricks -p <profile> deployments delete agent-bricks-<name>` | Managed Runtime Store cleanup checks the app identity and runs before app deletion; a cleanup failure retains the app for retry. Memory/session stores, tracing experiments, tools, and source files are retained. |
+| [Memory store](../cli.md#agentbricks-memory-stores-delete) | `agentbricks -p <profile> memory stores delete <resource-name>` | Soft-deletes the store after confirmation. |
+| [Session store](../cli.md#agentbricks-sessions-stores-delete) | `agentbricks -p <profile> sessions stores delete <name>` | Deletes the store after confirmation. |