---
section_id: "8-faq-reference"
title: "FAQ & Reference"
quality_score: null
provenance:
  source: "X-IPE source code + running application + documentation"
  extracted_by: "x-ipe-task-based-application-knowledge-extractor"
  extraction_date: "2026-03-17"
---

# 8. FAQ & Reference

## Instructions

This section provides frequently asked questions, a glossary, keyboard shortcuts, and API reference for the Ideation module.

## Content

### Frequently Asked Questions

#### Q: Can I use Ideation without AI agents?
**A:** Yes. You can create, organize, edit, and manage ideas entirely manually. AI refinement (via the Console) is optional — it enriches ideas with structured summaries, mockups, and architecture diagrams, but the core CRUD functionality works without it.

#### Q: Where are my ideas stored?
**A:** Ideas are stored as files and folders in `x-ipe-docs/ideas/` within your project directory. There is no database — everything is human-readable files on disk. You can browse, edit, or version-control these files with standard tools (VS Code, Git, etc.).

#### Q: How are idea summaries versioned?
**A:** Each time an AI agent generates or regenerates a summary, it creates a new versioned file: `idea-summary-v1.md`, `idea-summary-v2.md`, etc. Previous versions are never overwritten — they remain in the folder for reference.

#### Q: Can I move ideas between projects?
**A:** Yes. Since ideas are just folders on disk, you can copy or move them between project directories manually. Note that KB references (`.knowledge-reference.yaml`) may need path updates if the knowledge base location differs between projects.

#### Q: What happens if I delete an idea folder?
**A:** Deletion is permanent. The folder and all its contents (files, summaries, mockups, references) are removed from disk. There is no recycle bin or undo. If the idea is linked to a workflow, the workflow link is broken.

#### Q: Can multiple users work on ideas simultaneously?
**A:** X-IPE Ideation uses file-system storage with no built-in locking. If multiple users modify the same file concurrently, the last save wins. For collaborative scenarios, use Git-based version control on the `x-ipe-docs/ideas/` directory.

#### Q: What file formats can I upload?
**A:** Text (.md, .txt), Data (.json, .yaml, .xml, .csv), Code (.py, .js, .ts, .jsx, .tsx, .html, .css, .sh, .sql, .java, .c, .cpp, .go, .rs, .rb), Images (.png, .jpg, .gif, .svg, .webp), and Documents (.docx, .msg — auto-converted to HTML).

#### Q: How do I share an idea with someone who doesn't have X-IPE?
**A:** Use Copilot Actions → "Share Idea" to export to PPTX, PDF, or DOCX format. Alternatively, share the raw Markdown files directly — they're readable in any Markdown viewer.

#### Q: Can I import ideas from other tools?
**A:** Yes. Export your ideas as Markdown or text files from other tools and upload them via the Upload Files tab. DOCX and MSG files are also supported with automatic HTML conversion.

#### Q: How does the UIUX Reference tool work technically?
**A:** It uses the Chrome DevTools Protocol to connect to a browser, navigate to the target URL, and extract DOM elements, computed CSS styles, color palettes, and design tokens. The extracted data is saved as structured files (HTML, CSS, Markdown) in the idea folder.

---

### Glossary

| Term | Definition |
|------|-----------|
| **Idea Folder** | A directory in `x-ipe-docs/ideas/` containing all artifacts for a single idea (raw files, summaries, mockups, references) |
| **Idea Summary** | A structured Markdown document generated by AI, containing Overview, Problem Statement, Target Users, Proposed Solution, Key Features, User Workflow, Architecture, Success Criteria, and Implementation Roadmap |
| **Compose Idea** | The feature for writing ideas directly in the Markdown editor |
| **KB Reference** | A link from an idea to a Knowledge Base article, stored in `.knowledge-reference.yaml` |
| **UIUX Reference** | Design elements (colors, HTML/CSS, tokens) captured from a live web page |
| **Ideation Toolbox** | Configuration file (`.ideation-tools.json`) that controls which AI tools are available during refinement |
| **Workflow Mode** | Operating mode where ideas are linked to an engineering workflow with staged progression (Ideation → Requirements → Design → Implementation → Delivery) |
| **Free Mode** | Operating mode where ideas are managed independently without workflow linkage |
| **Architecture DSL** | X-IPE's domain-specific language for defining layered architecture diagrams, rendered as interactive SVG |
| **SimpleMDE** | The Markdown editor library used in X-IPE for composing and editing idea content |
| **Console** | The bottom panel in X-IPE where users interact with AI agents (GitHub Copilot CLI or OpenCode) |
| **Copilot Actions** | Context-aware AI actions available on idea files via the 🤖 button |
| **DAO** | Decision-making framework (Decentralized Autonomous Organization pattern) used by AI agents for autonomous operation |
| **Mermaid** | A JavaScript-based diagramming library used for rendering flowcharts, sequence diagrams, etc. from text definitions |

---

### Keyboard Shortcuts (Editor)

| Shortcut | Action | Context |
|----------|--------|---------|
| `Ctrl+B` / `⌘+B` | Bold text | Markdown editor |
| `Ctrl+I` / `⌘+I` | Italic text | Markdown editor |
| `Ctrl+K` / `⌘+K` | Insert link | Markdown editor |
| `F9` | Toggle Preview | Markdown editor |
| `F11` | Toggle Fullscreen | Markdown editor |
| `Esc` | Exit fullscreen / Cancel edit | Markdown editor |

---

### API Reference (Ideation Endpoints)

For developers and advanced users, here is a summary of the Ideation REST API:

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/ideas/tree` | Get the full idea folder tree |
| `GET` | `/api/ideas/<path>/content` | Get file content (rendered or raw) |
| `POST` | `/api/ideas/upload` | Upload files to an idea folder |
| `POST` | `/api/ideas/create-folder` | Create a new empty folder |
| `POST` | `/api/ideas/rename` | Rename a file or folder |
| `DELETE` | `/api/ideas/<path>` | Delete a file or folder |
| `GET` | `/api/ideas/<path>/delete-info` | Preview deletion (file count, subfolders) |
| `POST` | `/api/ideas/move` | Move a file or folder |
| `POST` | `/api/ideas/duplicate` | Duplicate a folder |
| `GET` | `/api/ideas/<folder>/toolbox` | Get toolbox configuration |
| `POST` | `/api/ideas/<folder>/toolbox` | Update toolbox configuration |
| `GET` | `/api/ideas/<folder>/kb-references` | Get Knowledge Base references |
| `POST` | `/api/ideas/<folder>/kb-references` | Save Knowledge Base references |
| `POST` | `/api/ideas/<folder>/save-content` | Save edited file content |
| `POST` | `/api/ideas/compose` | Create a new idea via compose |
| `POST` | `/api/ideas/<folder>/version` | Create a versioned summary |
| `POST` | `/api/ideas/drop-target-validate` | Validate a drag-and-drop target |

**Authentication:** No authentication is required for the local development server. For production deployments, configure authentication middleware as needed.

**Response Format:** All API responses use JSON format:
```json
{
  "success": true,
  "data": { ... }
}
```

Error responses:
```json
{
  "success": false,
  "error": "Error description"
}
```

## Screenshots

No additional screenshots for this section.
