Download the PHP package waaseyaa/bimaaji without Composer

waaseyaa/bimaaji

Bimaaji is a Waaseyaa package providing application graph introspection and an agent-safe mutation protocol. The name (Anishinaabemowin: "to give life to") reflects its role: making a booted Waaseyaa application's structure visible and actionable to AI agents.

What it does

Bimaaji exposes two surfaces:

1. Read-only introspection. Six GraphSectionProvider implementations (admin, entities, jsonapi, public_surface, routing, sovereignty) emit versioned GraphSection payloads that, taken together, describe what an application contains: registered entity types and their fields, every registered route plus access classification, the JSON:API surface, admin entity groupings, the current sovereignty profile, and the public-surface map.
2. Validated mutation. A MutationRequest → MutationValidator → PatchSet pipeline lets an agent propose changes (e.g., "add field X to entity Y"). The validator gates every request through SovereigntyGuardrails; the patch generator emits content-hashed, reviewable file patches. Bimaaji itself never writes to disk — patches are returned for human (or upstream agent) review.

Quick start

After installing waaseyaa/framework (which depends on this package), the framework's PackageManifestCompiler auto-discovers BimaajiServiceProvider. The application graph generator is then reachable from the container:

The six default section providers are pre-wired:

Filesystem-backed spec indexing is disabled by default. Applications that intentionally expose spec search to an authenticated bimaaji.read principal must configure a non-empty bimaaji.specs_directory; Bimaaji never guesses a project-root docs/specs path for a remotely callable tool.

SovereigntyProfile is derived from SovereigntyConfigInterface::getProfile() and falls back to SovereigntyProfile::Local when no config is bound. Route sections read the completed kernel RouteSnapshot lazily on each export. Bare explicitly supplied RouteCollection or WaaseyaaRouter compatibility applies only without a kernel accessor; invalid or incomplete kernel authority refuses.

Extending: third-party graph sections

A consuming package can contribute its own section by implementing GraphSectionProviderInterface and binding it in its own ServiceProvider::register(). The canonical tag is BimaajiServiceProvider::SECTION_PROVIDER_TAG (bimaaji.section_provider); tag your binding under it for forward-compatibility with future tagged-collection container support.

Installing guidelines / skills (bin/waaseyaa bimaaji:install)

Ship the framework-canonical agent skill pack to a consumer project in per-client formats. Lifted in spirit from Laravel Boost's php artisan boost:install; framework-native, no Node runtime.

The skills are resources of this package — resources/skills/<id>/SKILL.md — so the command reads the same directory whether it runs from the framework monorepo or from a consumer's vendor/waaseyaa/bimaaji. Nothing is read from the consuming project. An application with its own skill set points bimaaji.skills_directory at it.

Every generated file frames its payload in <!-- waaseyaa:bimaaji:install BEGIN --> / END markers. A re-run replaces only the text between them, so notes you write above or below the block survive upgrades. A target file that carries no markers is treated as wholly hand-authored and still needs --force (or an interactive confirmation) before it is replaced.

The command records what it generated in .waaseyaa/bimaaji-install.json (commit it) and prunes targets a later skill set no longer produces. Ownership is recorded, never inferred from a filename: a path the manifest does not claim is never touched, a retired target you have since edited is neutralised rather than deleted, and supporting files you add inside a generated skill directory survive.

For Claude Code the output is .claude/skills/waaseyaa-<id>/SKILL.md — one directory per skill, which is the only layout Claude Code discovers.

Seven launch clients: claude, cursor, codex, copilot, gemini, windsurf, junie. See docs/specs/bimaaji-install.md for the per-client target paths, flag semantics, interactive UX, exit codes, sandbox guarantees, and the five-step extension guide for adding new clients.

Status

Bimaaji is now exposed over MCP via packages/mcp/'s per-request bridge architecture as of 2026-05-23 (M3 bimaaji-mcp-bridge-01KS5VS8). Five #[AsAgentTool] adapters live in packages/ai-agent/src/Tool/Bimaaji/ and surface automatically through the AgentToolRegistryBridge with no per-tool MCP code. See docs/specs/mcp-endpoint.md § "Bimaaji MCP bridge" for the transport contract and packages/mcp/README.md for the operator-facing summary.

The 2026-05-20 "PHP-only" deferral that closed #1463 was formally superseded by M3; the issue stays closed with a supersession comment linking to the M3 PR set.

Legacy MCP-server cleanup (pre-M3 consumers)

Projects (e.g., Minoo) that previously wired the deleted Node-based bimaaji MCP server (vendor/waaseyaa/bimaaji/mcp/server.js, removed in #1387/#1464) should:

1. Remove any mcpServers.bimaaji entry pointing at the deleted server.js from .claude/settings.json. The replacement is the framework-native /mcp HTTP endpoint shipped by waaseyaa/mcp.
2. Drop composer bimaaji-mcp-install from post-install hooks or contributor docs — the script body was Minoo-local and has no upstream entry point.
3. Wire the new HTTP /mcp endpoint instead. See packages/mcp/README.md for the claude_desktop_config.json example fragment.

Where to read more

• Doctrine spec: docs/specs/bimaaji.md — design rationale, FRs/NFRs, invariants, file map.
• Design history: docs/history/plans/2026-05-21-ai-ecosystem-beta-tightening.md — the 5-mission cluster that promoted bimaaji from "scaffolding" to "shipped."
• Roadmap context: GitHub Milestone #67 (Track 2: Bimaaji & agentic).

Canonical route export uses the existing Symfony projection and raw JSON output. The optional collection/accessor constructor form retains direct caller compatibility. Installed FETDER and supported Linux qualification remain pending under #3122.