I Built a Infinite Variation Knowledge Base That AI Can Query — Here's How Kiro Made It Possible 🎃

Ketan Saraf — Fri, 05 Dec 2025 18:21:22 +0000

How I used specs, hooks, steering, and MCP integrations to build NEXUS in a weekend

Ever clicked a link in your notes app and immediately forgot what you were looking at before? Yeah, me too. That frustration led me to build NEXUS — a knowledge base template where clicking a link opens a new pane beside your current one, not instead of it.

But here's the twist: I built it for the Kiroween Hackathon, and Kiro's AI-powered IDE features turned what would've been a month-long project into a weekend sprint.

Let me show you how.

The Problem: Knowledge Tools Are Broken

I've tried them all:

Obsidian — Great linking, but click a link and poof, your context vanishes
GitBook — Perfect for linear docs, but no way to explore connections
Notion — Jack of all trades, master of none
Andy Matuschak's Notes — Chef's kiss for stacking panes, but not open source

I wanted something that combined:

Horizontal stacking — Click a link, new pane opens right, old one stays
Linear navigation — Prev/Next for documentation
Graph view — See how everything connects

And I wanted it to be AI-native — meaning Claude or any AI assistant could query my knowledge base directly.

Enter NEXUS: Three Ways to Explore

NEXUS is a skeleton template. One codebase, infinite possibilities.

To prove it, I built two completely different apps:

App	Vibe	Use Case
Arcana 🔮	Dark, mystical	Personal knowledge vault
Codex 📖	Light, professional	API documentation

Same code. Different YAML config. Completely different experiences.

# Arcana config
mode: "personal"
theme:
  preset: "dark"
  colors:
    primary: "#9333ea"
features:
  local_graph: true
  linear_nav: false

# Codex config
mode: "documentation"
theme:
  preset: "light"
  colors:
    primary: "#2563eb"
features:
  local_graph: false
  linear_nav: true

That's it. That's the difference.

How Kiro Changed Everything

Here's where it gets interesting. I didn't just use Kiro — I used every feature it offers. And the combination was more powerful than any individual piece.

1. Spec-Driven Development: Planning Before Coding

Kiro's spec system is like having a senior architect on your team who never gets tired.

For complex features like the multi-pane navigation, I created specs with three phases:

Requirements → What does the user need?

WHEN a user clicks a [[wikilink]]
THEN the System SHALL open a new pane to the right
WHILE keeping the previous pane visible

Design → How do we build it?

- NavigationContext manages pane state
- useReducer handles open/close/focus actions
- Horizontal scroll container with snap points

Tasks → What are the steps?

1. Create NavigationContext with pane state
2. Implement OPEN_PANE action
3. Add horizontal scroll container
4. Wire up wikilink click handlers

I created 16 specs total. Each one kept Kiro focused and prevented the "let me just refactor everything" syndrome that plagues AI coding.

2. Agent Hooks: Automation That Actually Works

This is the feature that made me go "wait, this is actually magic."

I set up three hooks that run automatically:

Code Quality Check — Runs on every .ts/.tsx save

{
  "when": { "type": "fileEdited", "patterns": ["src/**/*.ts"] },
  "then": { "prompt": "Fix TypeScript errors, add missing imports" }
}

Component Docs Generator — Auto-documents React components

{
  "when": { "type": "fileEdited", "patterns": ["**/components/**/*.tsx"] },
  "then": { "prompt": "Add JSDoc documentation to this component" }
}

Secrets Scanner — Catches API keys before they hit git

{
  "when": { "type": "fileEdited", "patterns": ["**/*.ts", "**/*.yaml"] },
  "then": { "prompt": "Scan for exposed secrets and alert if found" }
}

The result? Every file I saved was automatically:

Type-checked and fixed
Documented with JSDoc
Scanned for accidental credential exposure

No manual linting. No "oh crap I committed my API key" moments.

3. Steering Documents: Context That Persists

The biggest problem with AI coding assistants? They forget everything between sessions.

Kiro's steering documents solve this. I created three files in .kiro/steering/:

tech.md — The tech stack

- Next.js 14 (App Router) with TypeScript strict mode
- Tailwind CSS for styling
- Supabase (PostgreSQL) for database
- React Query v5 for server state
- TipTap for WYSIWYG editing

structure.md — Project conventions

- Barrel exports in hooks/, components/, types/
- Path alias @/_ maps to src/_
- Tests in **tests**/ folders adjacent to source

product.md — What we're building

NEXUS supports three navigation modes:

1. Horizontal (stacking panes)
2. Linear (prev/next)
3. Graphical (node graph)

Every time I started a new chat, Kiro already knew:

What libraries to use
How to structure code
What features exist

No more "actually, we're using React Query, not SWR" corrections.

4. MCP Integrations: No More Hallucinated Docs

This one's subtle but crucial.

AI models hallucinate documentation. They'll confidently tell you to use useQuery({ queryKey: 'users' }) when React Query v5 actually requires useQuery({ queryKey: ['users'] }).

Kiro's MCP integrations fix this by fetching real, current documentation:

Context7 MCP — Up-to-date Next.js, React Query, Supabase docs
TailwindCSS MCP — Accurate utility classes
21st.dev MCP — UI component patterns

Before MCP:

// Wrong v3 API
useQuery("users", fetchUsers);

After MCP:

// Correct v5 API
useQuery({ queryKey: ["users"], queryFn: fetchUsers });

Small difference. Hours of debugging saved.

The Vibe Coding Highlights

Not everything needed a spec. Some features just flowed through conversation:

"Create a wikilink parser that extracts [[links]] and handles aliases like [[Title|display text]]"

Kiro generated a complete links.ts module with regex parsing, alias handling, and autocomplete suggestions.

"Build an MCP server endpoint that exposes our notes as tools for AI agents"

Full implementation with list_pages, get_page, search, and ask tools. Input validation included.

"Make a local graph component showing the current note and its connections"

SVG-based force-directed graph with animated transitions and click-to-navigate.

Each of these would've taken me a day to research and implement. With Kiro? An hour each, tops.

The AI-Native Part

Here's the feature I'm most proud of: every NEXUS deployment can be an MCP server.

{
  "mcpServers": {
    "my-docs": {
      "url": "https://your-app.vercel.app/api/mcp"
    }
  }
}

Point Claude at your knowledge base and ask:

"What notes mention authentication?"
"Summarize my notes on React patterns"
"How do these three concepts connect?"

Your personal notes become AI-queryable. Your company docs become accessible to coding assistants.

We used AI tools to build tools for AI. Meta? Absolutely. Cool? Also yes.

The Numbers

16 specs created for major features
3 agent hooks automating quality checks
3 steering documents maintaining context
3 MCP integrations for accurate documentation
2 apps (Arcana + Codex) from one codebase
1 weekend to build it all

Without Kiro, this would've been a month-long project. The combination of specs + hooks + steering + MCP created a development flow I've never experienced before.

Try It Yourself

NEXUS is open source. Clone it, configure it, deploy it:

git clone https://github.com/yourname/nexus.git
cd nexus && npm install

# Add your Supabase credentials
npm run seed:arcana
npm run dev:arcana  # localhost:3001

Or just explore the code to see how the pieces fit together.

What I Learned

Specs prevent scope creep — When the AI knows exactly what to build, it doesn't wander
Hooks eliminate toil — Automating quality checks freed me to focus on features
Steering is underrated — Persistent context is the difference between "AI assistant" and "AI teammate"
MCP integrations matter — Accurate docs > hallucinated docs, every time

The future of coding isn't AI replacing developers. It's AI amplifying developers. Kiro showed me what that actually looks like.

Forge Master: Text-to-3D on Cloud Run GPU

Ketan Saraf — Tue, 11 Nov 2025 00:18:52 +0000

What We Built and Learned

TL;DR We built Forge Master, a small web app that turns short text prompts into production-ready 3D assets in about ninety seconds. It runs on Google Cloud Run with an NVIDIA L4 GPU, uses Imagen for crisp reference images, InstantMesh (Zero123++ + LRM) for reconstruction, and Gemini for prompt enhancement and QA.
This post is published for the purposes of entering the Cloud Run Hackathon.

Live demo: https://forge-master-frontend-525900378413.europe-west1.run.app
GitHub repo: https://github.com/Keshraf/forge/

Demo video

Why we chose Cloud Run GPU

We wanted to run real 3D reconstruction without managing clusters. Cloud Run GPU let us ship a container with PyTorch, Diffusers, and InstantMesh, scale from zero, and keep costs bounded. Pairing a public frontend with an IAM-protected GPU backend made it safe to open the demo to everyone.

Architecture at a glance

Frontend (Cloud Run): Next.js UI + React Three Fiber viewer
Agent service (Cloud Run): four agents for prompt enhancement, generation coordination, quality assurance, and iterative improvement
GPU service (Cloud Run GPU L4): Imagen → Zero123++ → LRM → post-process → export (GLB, OBJ, FBX, STL)
Cloud Storage: serves model files and multi-view images
Cloud Run IAM: only the Agent can call the GPU service

The weekend build: three things that worked

Small, explicit contracts between services.
Frontend calls POST /generate on the Agent; the Agent obtains an IAM token, invokes the GPU service, collects URLs and stats, runs QA, and returns a compact result. Clear payloads made debugging easy.
Reconstruction-friendly inputs.
We bias prompts toward centered objects, white background, and studio lighting. That single nudge reduced artifacts and improved mesh quality in Zero123++ and LRM.
A short, bounded “quality loop.”
We compute mesh stats (vertices, faces, watertightness) and have Gemini score semantic fidelity. If the score is low, we re-run once with adjusted guidance. Tight loops beat unbounded retries.

What we learned about running our own models on Cloud Run GPU

VRAM spikes happen. Zero123++ and LRM can spike memory. Fixing batch sizes, capping resolution, using FP16, and adding timeouts kept the service stable on a single L4.
Cold starts are manageable. Trimming model load and keeping post-processing minimal kept p95 under ~140s, with typical runs around ~90s.
Secure the expensive hop. The GPU path is IAM-gated. Browsers never call it directly, which kept the demo public without risking runaway costs.

Try it

Prompt idea: “A medieval fantasy sword with ornate handle, centered, white background, studio lighting.”
Inspect the mesh in the viewer and download GLB, OBJ, FBX, or STL.

Live demo: https://forge-master-frontend-525900378413.europe-west1.run.app
GitHub repo: https://github.com/Keshraf/forge/

This article is public and was created for the purposes of entering the Cloud Run Hackathon.

DEV Community: Ketan Saraf