aas-setup 1.0.1

package/configs/pi/themes/dracula.json

@@ -0,0 +1,87 @@
+{
+	"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"name": "dracula",
+	"vars": {
+		"background": "#282a36",
+		"currentLine": "#44475a",
+		"foreground": "#f8f8f2",
+		"comment": "#6272a4",
+		"cyan": "#8be9fd",
+		"green": "#50fa7b",
+		"orange": "#ffb86c",
+		"pink": "#ff79c6",
+		"purple": "#bd93f9",
+		"red": "#ff5555",
+		"yellow": "#f1fa8c",
+		"bgLight": "#343746",
+		"bgLighter": "#3c3f58",
+		"bgDark": "#21222c",
+		"bgGreenTint": "#2a3a2e",
+		"bgRedTint": "#3a2a2e",
+		"bgPurpleTint": "#2e2a3a"
+	},
+	"colors": {
+		"accent": "purple",
+		"border": "purple",
+		"borderAccent": "pink",
+		"borderMuted": "comment",
+		"success": "green",
+		"error": "red",
+		"warning": "yellow",
+		"muted": "comment",
+		"dim": "#545978",
+		"text": "foreground",
+		"thinkingText": "comment",
+
+		"selectedBg": "currentLine",
+		"userMessageBg": "bgLight",
+		"userMessageText": "foreground",
+		"customMessageBg": "bgPurpleTint",
+		"customMessageText": "foreground",
+		"customMessageLabel": "purple",
+		"toolPendingBg": "bgDark",
+		"toolSuccessBg": "bgGreenTint",
+		"toolErrorBg": "bgRedTint",
+		"toolTitle": "foreground",
+		"toolOutput": "comment",
+
+		"mdHeading": "orange",
+		"mdLink": "cyan",
+		"mdLinkUrl": "comment",
+		"mdCode": "green",
+		"mdCodeBlock": "foreground",
+		"mdCodeBlockBorder": "comment",
+		"mdQuote": "comment",
+		"mdQuoteBorder": "comment",
+		"mdHr": "comment",
+		"mdListBullet": "pink",
+
+		"toolDiffAdded": "green",
+		"toolDiffRemoved": "red",
+		"toolDiffContext": "comment",
+
+		"syntaxComment": "comment",
+		"syntaxKeyword": "pink",
+		"syntaxFunction": "green",
+		"syntaxVariable": "foreground",
+		"syntaxString": "yellow",
+		"syntaxNumber": "purple",
+		"syntaxType": "cyan",
+		"syntaxOperator": "pink",
+		"syntaxPunctuation": "foreground",
+
+		"thinkingOff": "#545978",
+		"thinkingMinimal": "comment",
+		"thinkingLow": "cyan",
+		"thinkingMedium": "purple",
+		"thinkingHigh": "pink",
+		"thinkingXhigh": "red",
+
+		"bashMode": "green"
+	},
+	"export": {
+		"pageBg": "#1e1f29",
+		"cardBg": "bgDark",
+		"infoBg": "#3a3728"
+	}
+}

package/configs/pi/themes/kanagawa.json

@@ -0,0 +1,88 @@
+{
+	"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"name": "kanagawa",
+	"vars": {
+		"background": "#1F1F28",
+		"currentLine": "#363646",
+		"foreground": "#DCD7BA",
+		"comment": "#727169",
+		"cyan": "#7FB4CA",
+		"green": "#98BB6C",
+		"orange": "#FFA066",
+		"pink": "#D27E99",
+		"purple": "#957FB8",
+		"red": "#FF5D62",
+		"yellow": "#E6C384",
+		"blue": "#7E9CD8",
+		"bgLight": "#2A2A37",
+		"bgLighter": "#363646",
+		"bgDark": "#16161D",
+		"bgGreenTint": "#2A2E27",
+		"bgRedTint": "#2E2626",
+		"bgPurpleTint": "#26262E"
+	},
+	"colors": {
+		"accent": "cyan",
+		"border": "cyan",
+		"borderAccent": "blue",
+		"borderMuted": "comment",
+		"success": "green",
+		"error": "red",
+		"warning": "orange",
+		"muted": "comment",
+		"dim": "#54546D",
+		"text": "foreground",
+		"thinkingText": "comment",
+
+		"selectedBg": "currentLine",
+		"userMessageBg": "bgLight",
+		"userMessageText": "foreground",
+		"customMessageBg": "bgPurpleTint",
+		"customMessageText": "foreground",
+		"customMessageLabel": "purple",
+		"toolPendingBg": "bgDark",
+		"toolSuccessBg": "bgGreenTint",
+		"toolErrorBg": "bgRedTint",
+		"toolTitle": "foreground",
+		"toolOutput": "comment",
+
+		"mdHeading": "orange",
+		"mdLink": "cyan",
+		"mdLinkUrl": "comment",
+		"mdCode": "green",
+		"mdCodeBlock": "foreground",
+		"mdCodeBlockBorder": "comment",
+		"mdQuote": "comment",
+		"mdQuoteBorder": "comment",
+		"mdHr": "comment",
+		"mdListBullet": "pink",
+
+		"toolDiffAdded": "green",
+		"toolDiffRemoved": "red",
+		"toolDiffContext": "comment",
+
+		"syntaxComment": "comment",
+		"syntaxKeyword": "red",
+		"syntaxFunction": "blue",
+		"syntaxVariable": "foreground",
+		"syntaxString": "green",
+		"syntaxNumber": "purple",
+		"syntaxType": "yellow",
+		"syntaxOperator": "red",
+		"syntaxPunctuation": "foreground",
+
+		"thinkingOff": "#54546D",
+		"thinkingMinimal": "comment",
+		"thinkingLow": "cyan",
+		"thinkingMedium": "purple",
+		"thinkingHigh": "pink",
+		"thinkingXhigh": "red",
+
+		"bashMode": "green"
+	},
+	"export": {
+		"pageBg": "#16161D",
+		"cardBg": "bgDark",
+		"infoBg": "#2A2E27"
+	}
+}

package/configs/reference/MEMORY.md

@@ -0,0 +1,239 @@
+# 🚀 MEMORY.md - AI Agent Knowledge Management
+
+**Purpose**: Tell agents when to use **qmd** (durable project KB), when to use **agentmemory** (session-only learnings), and when to skip recording entirely. Cross-session task continuity goes through `/handoffs` + `/pickup`, not these stores.
+
+---
+
+## 📋 Pre-flight Check: Is Knowledge Base Ready?
+
+Before using qmd knowledge features, check if the project's knowledge base is set up:
+
+```bash
+# Check if qmd is installed
+command -v qmd || echo "qmd not found - install with: bun install -g @tobilu/qmd"
+
+# Check if MCP server is configured (should return qmd server info)
+mcp__qmd__status
+
+# Check if project collection exists
+qmd collection list
+```
+
+**If NOT set up for this project, automatically set it up:**
+
+```bash
+# Auto-detect project name: try git remote, fallback to repo folder name, then current folder
+PROJECT_NAME=$(
+  { git remote get-url origin 2>/dev/null | xargs basename -s .git 2>/dev/null; } ||
+  { git rev-parse --show-toplevel 2>/dev/null | xargs basename; } ||
+  basename "$PWD"
+)
+
+# Filter out empty or invalid values (like "origin" or URL-like strings)
+if [ -z "$PROJECT_NAME" ] || [ "$PROJECT_NAME" = "origin" ] || [[ "$PROJECT_NAME" =~ ^[./:] ]]; then
+  PROJECT_NAME=$(
+    { git rev-parse --show-toplevel 2>/dev/null | xargs basename; } ||
+    basename "$PWD"
+  )
+fi
+
+# 1. Create project directory structure
+mkdir -p ~/.ai-knowledges/$PROJECT_NAME/learnings
+mkdir -p ~/.ai-knowledges/$PROJECT_NAME/issues
+
+# 2. Add to qmd (check for existing collection more robustly)
+ERR_FILE="/tmp/qmd-collection-add-$$.err"
+if qmd collection add ~/.ai-knowledges/$PROJECT_NAME --name $PROJECT_NAME 2>"$ERR_FILE"; then
+  echo "✓ Collection '$PROJECT_NAME' added"
+  rm -f "$ERR_FILE"
+elif grep -qi "already exists" "$ERR_FILE" 2>/dev/null; then
+  echo "✓ Collection '$PROJECT_NAME' already exists"
+  rm -f "$ERR_FILE"
+elif qmd collection list 2>/dev/null | grep -q "^$PROJECT_NAME$"; then
+  echo "✓ Collection '$PROJECT_NAME' already exists"
+  rm -f "$ERR_FILE"
+else
+  echo "⚠ Warning: Could not verify collection setup"
+  rm -f "$ERR_FILE"
+fi
+
+# 3. Add context (skip if already exists)
+qmd context add qmd://$PROJECT_NAME "Knowledge base for $PROJECT_NAME project" 2>/dev/null || true
+
+# 4. Generate embeddings for search
+qmd embed 2>/dev/null || true
+
+# Inform user
+echo "✓ Knowledge base initialized for: $PROJECT_NAME"
+echo "  Storage: ~/.ai-knowledges/$PROJECT_NAME"
+```
+
+---
+
+## 📚 When to Use qmd Knowledge
+
+**DO use qmd for:**
+
+- Project-specific learnings (architecture decisions, gotchas, patterns)
+- Issue resolution notes (how you fixed something)
+- Project conventions and standards
+- Context that should persist across sessions
+
+**DON'T use for:**
+
+- Temporary debugging context (use `/handoffs` and `/pickup` instead)
+- General programming knowledge (already in your training)
+- Obvious implementations
+- Boilerplate code
+
+---
+
+## 🧠 Agentmemory (session memory MCP)
+
+`agentmemory` is a per-session, per-project memory MCP for **short-lived learnings that the agent itself discovered during the current run**. It is _not_ durable storage and _not_ a substitute for qmd.
+
+### Use `agentmemory` for (session-only, not durable)
+
+- Discoveries made in _this_ run: "the build is blocked on env var `X`", "branch Y has a WIP constraint", "the failing test depends on fixture Z"
+- Pre-commit / post-commit style findings the _current_ agent wants to surface to itself on the next pass
+- Hints the next session today will need but no one will need in a month
+
+### Do NOT use `agentmemory` for
+
+- Anything that survives a session boundary with value — that is qmd
+- Recurring gotchas, project-local facts, architecture smells, code review notes — these are durable and belong in qmd
+- Long-form docs, ADRs, runbooks — write to disk and let qmd index them
+- Cross-project or cross-machine knowledge — qmd collections are the canonical layer
+- Cross-session task continuity — use `/handoffs` (write) and `/pickup` (resume), not agentmemory
+- Secrets, tokens, or anything user-private (memory is per-project, not encrypted)
+
+### Decision rule (apply before every record)
+
+> "Will the next agent working on this project benefit from this in 3 months?"
+>
+> - **Yes** → `mcp__qmd__*` (`/qmd-knowledge` skill)
+> - **No, but the next session today might** → `mcp__agentmemory__memory_save`
+> - **No at all** → don't record
+> - **"I need to keep working on this tomorrow"** → write a `/handoffs` plan, not a memory note
+
+### Three memory lanes
+
+| Lane          | Horizon             | Tool                                              |
+| ------------- | ------------------- | ------------------------------------------------- |
+| `qmd`         | Months              | `mcp__qmd__save` via `/qmd-knowledge` skill       |
+| `agentmemory` | Today, same project | `mcp__agentmemory__memory_save`                   |
+| `/handoffs`   | Cross-session task  | `/handoffs` slash command → resume with `/pickup` |
+
+If you find yourself wanting both "remember this for me next time" and "let me continue this tomorrow" — that is two separate stores; pick the lane that matches the actual horizon.
+
+---
+
+## 🛠️ How to Use qmd (via MCP Server)
+
+When qmd MCP server is configured, you can autonomously:
+
+### Search Knowledge
+
+```text
+mcp__qmd__query - for best quality (hybrid search with reranking)
+mcp__qmd__search - for fast keyword search
+mcp__qmd__vsearch - for semantic similarity search
+```
+
+### Read Documents
+
+```text
+mcp__qmd__get - get single document by path or docid
+mcp__qmd__multi_get - get multiple by glob pattern
+```
+
+### Check Status
+
+```text
+mcp__qmd__status - see collections and health
+```
+
+---
+
+## 📝 What About Recording?
+
+### 🚫 Do not directly write to ~/.ai-knowledges/
+
+Instead, use the `qmd-knowledge` skill:
+
+- Invoke via `/qmd-knowledge` slash command
+- Agent will handle proper file creation and embedding updates
+
+---
+
+## 📋 Best Practices
+
+### 🎨 Session Wrap-up
+
+At the end of a work session, consider prompting the user about key learnings:
+
+> "What were the main discoveries or decisions from this session? Would you like me to record any learnings — and if so, into qmd (durable) or agentmemory (session)?"
+
+### 🎨 Pattern Detection → Decision Rule
+
+When you spot a knowledge-capture trigger, **apply the 3-month rule first**, then choose a lane.
+
+| Phrase                                       | Lane                                    |
+| -------------------------------------------- | --------------------------------------- |
+| "I learned that…" / "The fix was…" (general) | Usually qmd — unless it is session-only |
+| "Blocked on X until env var Y"               | `agentmemory` (session)                 |
+| "Branch W has a WIP constraint"              | `agentmemory` (session)                 |
+| "Don't forget to…" / recurring gotcha        | qmd (durable)                           |
+| "This project uses pattern P"                | qmd (durable, project-local)            |
+| "Continue debugging tomorrow" / "resume X"   | `/handoffs` + `/pickup` (not memory)    |
+
+If unsure, ask the user which lane — never record into both.
+
+### 🎨 Auto-Index Updates
+
+The record script automatically runs `qmd embed` after each write, ensuring the knowledge base is searchable immediately. No manual re-indexing required.
+
+---
+
+## 📖 Quick Reference
+
+All tools are MCP-style names so agents can call them by exact string.
+
+### qmd (durable)
+
+| Task             | Tool/Command           |
+| ---------------- | ---------------------- |
+| Search knowledge | `mcp__qmd__query`      |
+| Get document     | `mcp__qmd__get`        |
+| Record learning  | `/qmd-knowledge` skill |
+| Check status     | `mcp__qmd__status`     |
+
+### agentmemory (session)
+
+| Task                     | Tool                                         |
+| ------------------------ | -------------------------------------------- |
+| Save a finding           | `mcp__agentmemory__memory_save`              |
+| Recall past findings     | `mcp__agentmemory__memory_recall`            |
+| Hybrid recall + rerank   | `mcp__agentmemory__memory_smart_search`      |
+| List recent sessions     | `mcp__agentmemory__memory_sessions`          |
+| Export memory            | `mcp__agentmemory__memory_export`            |
+| Audit memory             | `mcp__agentmemory__memory_audit`             |
+| Delete a specific memory | `mcp__agentmemory__memory_governance_delete` |
+
+---
+
+## 🔍 Project Detection
+
+The `qmd-knowledge` skill auto-detects project from:
+
+1. `QMD_PROJECT` env var (if set)
+2. Git repository name
+3. Current directory name
+
+Knowledge is stored in `~/.ai-knowledges/{project-name}/`
+
+---
+
+## 🔗 See Also
+
+- [qmd GitHub](https://github.com/tobi/qmd) - qmd tool documentation

package/configs/reference/agent-memory.md

@@ -0,0 +1,5 @@
+# Agent Memory Guidelines
+
+- Auto-capture learnings as you work: save decisions, debugging discoveries, user preferences, and tool quirks using `mem_save` (agentmemory) — do not wait to be asked.
+- After fixing a non-trivial bug or learning something project-specific, persist it immediately so future sessions benefit.
+- Keep memories concise and actionable — prefer facts and patterns over narrative.

package/configs/reference/best-practices.md

@@ -0,0 +1,270 @@
+# Software Development Best Practices
+
+## AI Tool Session Management
+
+### Run Commands in tmux for Debuggability
+
+Always run long-running commands, development servers, tests, and interactive sessions inside tmux with the **current directory name as the session name**. This enables easy debugging and monitoring.
+
+```bash
+# Create session named after current directory (e.g., "my-project")
+SESSION=$(basename "$PWD")
+tmux new -d -s "$SESSION" 2>/dev/null || true
+
+# Run dev server with portless if available, otherwise fallback to npm
+if command -v portless &>/dev/null; then
+    tmux send-keys -t "$SESSION" 'portless run npm run dev' Enter
+else
+    tmux send-keys -t "$SESSION" 'npm run dev' Enter
+fi
+
+# To check status later from another terminal:
+tmux ls                          # list all sessions
+tmux attach -t my-project        # attach to debug
+tmux capture-pane -p -t my-project -S -100  # view last 100 lines without attaching
+```
+
+**Benefits:**
+
+- Sessions survive terminal disconnects
+- Stable `.localhost` URLs via portless (no port numbers to remember)
+- Easy to reattach and debug from any terminal
+- Capture output without interrupting the process
+- Multiple users/agents can monitor the same session
+
+**Best Practice:** For AI-assisted log analysis, pair with [LogPilot](https://github.com/machuqiji/logpilot):
+
+```bash
+logpilot watch "$SESSION" --pane "$SESSION:0.0"
+```
+
+**Example package.json:**
+
+```json
+{
+	"scripts": {
+		"dev": "portless run next dev"
+	}
+}
+```
+
+---
+
+## Context
+
+Comprehensive development guidelines for Agent OS projects, based on Kent Beck's "Tidy First?" principles and Kent C. Dodds' programming wisdom.
+
+> "Software design is an exercise in human relationships" - Kent Beck
+
+## 🎯 Core Principles
+
+### 🧹 Tidy First Philosophy
+
+- **Small, Safe Steps**: Make big changes through small, reversible steps
+- **Human Relationships**: Code is communication between humans
+- **Economic Thinking**: Balance current effort against future options
+- **Eliminate Problems**: Remove complexity rather than managing it
+
+### ✨ Code Quality Fundamentals
+
+- **Don't Solve Problems, Eliminate Them**: Look for ways to reduce complexity
+- **Optimize for Readability**: Prioritize code clarity over clever solutions
+- **Self-Documenting Code**: Use meaningful names and clear structure
+- **Test for Confidence**: Write tests that give confidence to change
+
+### 🔄 Change-Friendly Design
+
+- **Separate Tidying from Behavior Changes**: Keep refactoring separate from new features
+- **Build for the Next Developer**: Consider maintainability and understanding
+- **Options Over Things**: Create flexibility for uncertain future requirements
+- **Progressive Enhancement**: Start simple, add complexity when needed
+
+## 📦 Dependencies
+
+### 🧠 Choose Libraries Wisely
+
+When adding third-party dependencies:
+
+- Select the most popular and actively maintained option
+- Check the library's GitHub repository for:
+  - Recent commits (within last 6 months)
+  - Active issue resolution
+  - Number of stars/downloads
+  - Clear documentation
+
+## 🧹 Tidying Practices
+
+### ⏰ When to Tidy
+
+**Before making a change**:
+
+- Will tidying make the change easier? → Yes → Tidy first
+- Will tidying take longer than the change? → No → Make change first, tidy after
+- Is the change urgent? → Skip tidying for now, schedule for later
+
+### 🔧 Core Tidying Techniques
+
+#### 🛡️ Guard Clauses
+
+Move preconditions to the top and return early:
+
+```javascript
+// ❌ Nested conditions
+function processUser(user) {
+	if (user) {
+		if (user.isActive) {
+			if (user.hasPermission) {
+				// main logic
+			}
+		}
+	}
+}
+
+// ✅ Guard clauses
+function processUser(user) {
+	if (!user) return;
+	if (!user.isActive) return;
+	if (!user.hasPermission) return;
+
+	// main logic
+}
+```
+
+#### 🗑️ Dead Code Elimination
+
+Delete code that isn't executed or referenced.
+
+#### ⚖️ Normalize Symmetries
+
+Use consistent patterns throughout the codebase.
+
+#### 🆘 Helper Variables and Functions
+
+Extract complex expressions into well-named variables:
+
+```javascript
+// ❌ Complex expression
+if (
+	user.subscription.plan.tier === "premium" &&
+	user.subscription.status === "active" &&
+	user.subscription.expiresAt > new Date()
+) {
+	// logic
+}
+
+// ✅ Helper variable
+const hasActivePremiumSubscription =
+	user.subscription.plan.tier === "premium" &&
+	user.subscription.status === "active" &&
+	user.subscription.expiresAt > new Date();
+
+if (hasActivePremiumSubscription) {
+	// logic
+}
+```
+
+## 🧪 Testing Strategy
+
+### 🏆 The Testing Trophy Approach
+
+Based on Kent C. Dodds' testing philosophy:
+
+```
+    🏆 End-to-End (E2E)
+      ↑ High confidence, slow, expensive
+   🥉 Integration Tests
+      ↑ Good confidence, moderate speed
+  🥈 Unit Tests
+      ↑ Low confidence, fast, cheap
+ 🏅 Static Analysis
+```
+
+### 📝 Testing Guidelines
+
+#### 💪 Write Tests That Give Confidence
+
+- Test behavior, not implementation details
+- Focus on user-facing functionality
+- Prefer integration tests over isolated unit tests
+
+#### 🏗️ Test Structure
+
+```javascript
+// ✅ Clear test structure
+test("should increment counter when button is clicked", () => {
+	// Arrange
+	render(<Counter />);
+	const button = screen.getByRole("button", { name: /increment/i });
+	const counter = screen.getByTestId("counter-value");
+
+	// Act
+	expect(counter).toHaveTextContent("0");
+	fireEvent.click(button);
+
+	// Assert
+	expect(counter).toHaveTextContent("1");
+});
+```
+
+#### 🙈 Avoid Testing Implementation Details
+
+- Don't test internal state or private methods
+- Test the component's public interface
+- Mock at the network boundary, not internal functions
+
+## ⚡ Performance Practices
+
+### 📊 Optimize for the Right Metrics
+
+- Focus on user-centric performance (loading, interaction)
+- Measure before optimizing
+- Avoid premature micro-optimizations
+
+### 📈 Progressive Enhancement
+
+- Build core functionality that works without JavaScript
+- Enhance with client-side features
+- Use lazy loading for non-critical resources
+
+### 🚀 Performance Patterns
+
+```javascript
+// ✅ Lazy loading with Suspense
+const HeavyComponent = lazy(() => import("./heavy-component"));
+
+function App() {
+	return (
+		<Suspense fallback={<Skeleton />}>
+			<HeavyComponent />
+		</Suspense>
+	);
+}
+```
+
+## 🤝 Collaboration Practices
+
+### 💬 Code as Communication
+
+- Express intent clearly through naming and structure
+- Document decisions, not implementation
+- Consider the next developer who will read this code
+
+### 🔍 Pull Request Guidelines
+
+**For Authors**:
+
+- Separate tidying commits from behavior changes
+- Write clear commit messages
+- Include context in PR descriptions
+
+**For Reviewers**:
+
+- Focus on correctness, simplicity, and maintainability
+- Ask questions when unclear
+- Praise good solutions
+
+### ♻️ Continuous Improvement
+
+- Reflect on decisions and learn from mistakes
+- Share knowledge through documentation and mentoring
+- Regularly refactor and clean up technical debt