Quickstart: Your AI Developer Workspace

Navigate to Admin → Modules and enable aeion-forge. The MCP handler registers automatically — your AI agents (Claude, GPT, custom) can immediately call all 160+ Forge actions over MCP without any wiring.

Module dependencies installed automatically:

• Forge collections — projects, issues, sprints, knowledge entries, ADRs, file registry, agent sessions, time logs, focus workspaces
• MCP handler — exposes mcp__aeionos__forge to any agent connected via MCP
• Event bus — issue and sprint lifecycle events (forge.issue.created, forge.sprint.completed, etc.) publish to the platform event bus, so Blueprint or your own module can subscribe and trigger downstream automation
• Nightly memory consolidation — one scheduled job re-embeds changed knowledge, runs freshness checks, mines promotions, and cleans up stale sessions automatically; daily standup digests (generate_pulse) are generated on demand by agents, not on a fixed schedule

Confirm the install worked by opening Admin → Forge → Dashboard — you should see an empty project list (until Step 2) with no errors, and the MCP handler is live as soon as the module shows as enabled.

Forge exposes generate_embeddings and semantic_search_knowledge MCP actions so AI agents can retrieve knowledge by meaning rather than keyword. The embedding model is selected through the platform AI gateway — whichever provider you've configured for embeddings under Admin → AI → Providers (Aeion's standard provider registry) becomes the default for Forge as well.

```typescript // Backfill embeddings for an existing project (run once after migration) await aeion.forge({ action: "generate_embeddings", projectId: "PLAT", });

// Re-embed only documents that changed since the last pass (lighter; safe to schedule daily) await aeion.forge({ action: "reingest_changed", projectId: "PLAT", });

// Search knowledge by meaning const hits = await aeion.forge({ action: "semantic_search_knowledge", projectId: "PLAT", query: "how do we handle token rotation", limit: 10, }); ```

Keyword fallback — when an embedding provider isn't configured (or for projects that haven't been embedded yet), search_knowledge falls back to an ILIKE-based text search across title + content. Agents that need broad coverage call both: keyword-first for exact matches, semantic-second for adjacent concepts.

Freshness hygiene — check_knowledge_freshness runs three detectors: code drift (entries snapshot a structural fingerprint of the files they describe — rewritten code flags the entry no matter how recently it was edited), unverified age (90 days), and never-accessed (60+ days with zero retrievals). verify_knowledge resets the clocks; suggest_promotions mines recent resolutions for patterns that should graduate to permanent entries. A nightly consolidate_memory pass runs all of it automatically and renders a Memory Health summary in every session briefing.

Write-time dedup — create_knowledge and capture_learning refuse near-duplicates with the matching entries and a reconciliation hint (force: true overrides), so the knowledge base stays clean at the source instead of getting audited months later.

One glob call gives agents a queryable map of your code — symbols, call graph, and (once embedded) natural-language code search.

```typescript // Index a module — ignore rules + content-hash dedup make re-runs free await aeion.forge({ action: "index_codebase", projectId: "PLAT", glob: "src/**", });

// After every commit: keep the index tracking HEAD (you run git, Forge indexes) await aeion.forge({ action: "reindex_changed_code", projectId: "PLAT", paths: gitDiffNameOnly, // output of git diff --name-only HEAD~1 });

// Build the call graph from extracted callee names (dryRun previews counts) await aeion.forge({ action: "resolve_symbol_edges", projectId: "PLAT" });

// Now agents can ask real questions: await aeion.forge({ action: "search_symbols", projectId: "PLAT", query: "rate limit", }); await aeion.forge({ action: "get_symbol_usage", projectId: "PLAT", symbolName: "AuthService", }); // + transitive callers await aeion.forge({ action: "get_symbol_source", projectId: "PLAT", symbolId: "<from search>", }); await aeion.forge({ action: "simulate_blast_radius", projectId: "PLAT", symbolName: "AuthService", }); ```

Trust by design — name collisions are everywhere in real codebases (setup, handler), so edge resolution prefers same-file definitions, accepts project-unique ones, and skips ambiguous names while _reporting the count_. The graph re-resolves automatically per file after every reindex.

The killer feature: agents start with full project context via get_session_handoff. Zero ramp-up time.

```typescript // Agent invokes at the start of every session const handoff = await aeion.forge({ action: "get_session_handoff", projectId: "PLAT", });

// handoff includes: // - Last session's nextAction (where to pick up) // - Active sprint progress (X / Y issues done) // - In-progress issues + blockers // - Recent decisions // - Key knowledge entries // - Dead ends from previous agents (avoid re-trying) // - Files the next agent should read first ```

Agent best practices:

1. Start every session with get_session_handoff — read it before doing anything else.
2. Sync memory with sync_agent_memory so other agents can see what you're working on (avoids parallel duplicate work).
3. Use file locks (claim_file_lock / release_file_lock) when editing shared files.
4. Dedupe before creating — call get_similar_issues before create_issue to avoid spam.
5. Capture learnings — call capture_learning when you discover something non-obvious. It becomes part of the searchable knowledge base.
6. End every session with complete_session — record what shipped, what's next, what failed.

Sprints are time-boxed iteration windows. Aeion Forge's sprint engine tracks velocity, burndown, and auto-rolls incomplete work.

```typescript // Create a sprint const sprint = await aeion.forge({ action: "create_sprint", projectId: "PLAT", sprintName: "Sprint 12 — Q3 Velocity", sprintGoal: "Ship the multi-tenant audit-log signing rollout", sprintDuration: 14, // Days });

// Move issues into the sprint await aeion.forge({ action: "move_to_sprint", issueIds: ["PLAT-101", "PLAT-102", "PLAT-103"], sprintId: sprint.id, });

// Start the sprint await aeion.forge({ action: "start_sprint", sprintId: sprint.id, }); ```

During the sprint:

• generate_pulse produces a daily standup digest (what shipped yesterday, what's planned today, who's blocked)
• get_blocked_issues surfaces work stuck waiting on dependencies
• calculate_critical_path finds the longest dependency chain that could slip the sprint
• add_comment + link_pr track PR-to-issue lifecycle

At sprint end:

• complete_sprint archives the sprint with a retrospective
• generate_release_notes produces customer-facing changelog markdown from shipped issues
• export_sprint_report emits a full markdown report for stakeholders

Incomplete issues automatically move to the next sprint or back to the backlog (configurable).

Link PRs to issues so merge state auto-updates issue status, and so review status surfaces in your project boards.

```typescript // Attach a PR to an issue await aeion.forge({ action: "link_pr", issueId: "PLAT-101", prUrl: "https://github.com/acme/platform/pull/4287", prTitle: "feat: multi-tenant audit-log signing", });

// When the PR merges, auto-close the issue await aeion.forge({ action: "update_pr_status", prUrl: "https://github.com/acme/platform/pull/4287", prStatus: "merged", autoClose: true, // Closes the issue on merge }); ```

GitHub webhook configuration:

1. In your GitHub repo, go to Settings → Webhooks → Add webhook
2. Set the payload URL to your Aeion instance's /api/v1/forge/webhooks/github endpoint, content type application/json, and the secret your platform administrator configured
3. Subscribe to the Pull request event — that's what drives the auto-transitions and comment-linking described above today

PR comments by AI agents flow through the attach_commit action with the issue ID, so the full review thread is searchable later.