ace-idea 0.18.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8994e5d86e56e55d0f5a6bb8bcf3d492bf54cf6a57c0cd9dbc4e7dc5918ee9f0
+  data.tar.gz: b31f01f126a87d8d0cba9a9e4ff7b428dd9438f7757a402ee77914fd9c582a75
+SHA512:
+  metadata.gz: 97b27dfac510f4dc695d75c5720282c0d131f17e9ed0c501e095af0cb033f814019a4a26599e69027b09215303dc6ad3e17d360ce709efdb58f6133c69cc8709
+  data.tar.gz: f40ce5aa2082d5c1e3f0ba6e59f9d5948b6c54812c71ea9fac556b3bf605f91f62c3f3d55bafacf6b80f542d29f334a5bee4a49ae8cfc6c254b62aea03cc5b72

data/.ace-defaults/idea/config.yml

@@ -0,0 +1,21 @@
+# ace-idea default configuration
+idea:
+  # Root directory for ideas storage
+  root_dir: .ace-ideas
+
+  # Default status for new ideas
+  default_status: pending
+
+  # LLM model for idea enhancement
+  llm_model: gemini:flash-latest
+
+  # LLM model for doctor --auto-fix-with-agent
+  doctor_agent_model: gemini:flash-latest@yolo
+
+  # Status command: default limits
+  status:
+    up_next_limit: 7
+    recently_done_limit: 7
+
+  # Prefix used to identify special folders (e.g., "_archive", "_maybe")
+  special_folder_prefix: "_"

data/.ace-defaults/nav/protocols/wfi-sources/ace-idea.yml

@@ -0,0 +1,19 @@
+---
+# WFI Sources Protocol Configuration for ace-idea gem
+# This enables workflow discovery from the installed ace-idea gem
+
+name: ace-idea
+type: gem
+description: Idea management workflow instructions from ace-idea gem
+priority: 10
+
+# Configuration for workflow discovery within the gem
+config:
+  # Relative path within the gem (default: handbook/workflow-instructions)
+  relative_path: handbook/workflow-instructions
+
+  # Pattern for finding workflow files (default: *.wf.md)
+  pattern: "*.wf.md"
+
+  # Enable discovery
+  enabled: true

data/CHANGELOG.md

@@ -0,0 +1,387 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.18.0] - 2026-03-23
+
+### Fixed
+- Corrected `--enhance` flag reference in README to `--llm-enhance` matching the actual CLI option.
+
+### Changed
+- Updated gemspec summary to align with README tagline emphasizing the capture-to-execution lifecycle.
+- Rewrote folder documentation to clarify that folders are user-defined; only `_archive` has special behavior.
+- Updated `--move-to` option descriptions in usage docs to reflect any-named-folder support.
+- Added `ace-idea status` example output to usage reference.
+- Documented clipboard platform behavior in getting-started prerequisites (macOS rich vs generic fallback).
+- Re-recorded getting-started demo with list, create, archive, and status scenes running in the main project.
+
+## [0.17.4] - 2026-03-23
+
+### Changed
+- Refreshed `README.md` to match the new package layout pattern with logo/badges, quick links, and use-case-led positioning.
+
+## [0.17.3] - 2026-03-22
+
+### Technical
+- Aligned the getting-started demo tape output path with the checked-in asset.
+- Updated prioritize workflow wording to use current queue terminology instead of backlog language.
+
+## [0.17.2] - 2026-03-22
+
+### Fixed
+- Clarified the README, getting-started guide, and usage reference so the `next` queue is documented as the root-scope view rather than a physical `_next` folder.
+
+## [0.17.1] - 2026-03-22
+
+### Fixed
+- Replaced Kramdown-only code block markup with fenced Markdown blocks in the getting-started and usage docs.
+- Added `docs/**/*` to the gemspec file manifest so the packaged gem ships the documentation files linked from the README.
+
+## [0.17.0] - 2026-03-22
+
+### Changed
+- Reworked the package documentation with a landing-page README, tutorial getting-started guide, full usage reference, handbook catalog, demo assets, refreshed gem metadata messaging, and updated idea workflows to match the current six-command CLI.
+
+## [0.16.0] - 2026-03-20
+
+### Changed
+- Expanded `TS-IDEA-001` E2E lifecycle coverage with a new archive-transition goal and aligned list-filter runner/verifier contracts with root-scope behavior.
+
+## [0.15.1] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.15.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.14.4] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.14.3] - 2026-03-13
+
+### Changed
+- Updated the canonical idea review skill to explicitly run its bundled workflow in the current project and execute it end-to-end.
+
+## [0.14.2] - 2026-03-12
+
+### Changed
+- Updated the idea-lifecycle E2E runner instructions to capture the created idea file path and frontmatter content as first-class artifacts.
+
+## [0.14.1] - 2026-03-08
+
+### Technical
+- Removed obsolete doctor CLI test coverage for deleted `provider_cli_args` behavior and corrected quiet-mode unhealthy test block closure.
+
+## [0.14.0] - 2026-03-08
+
+### Changed
+- Remove hardcoded `providers.cli_args` config; use ace-llm `@preset` suffixes for provider permission flags
+
+## [0.13.5] - 2026-03-06
+
+### Fixed
+- `ace-idea list` now prints the summary line even when no ideas match the current scope.
+
+## [0.13.4] - 2026-03-05
+
+### Fixed
+- Legacy `cancelled` idea statuses are now normalized to `obsolete` in idea loading and display stats so `ace-idea list` no longer surfaces a non-canonical status bucket.
+
+### Changed
+- Frontmatter validation now emits a warning when derived `location` metadata is stored in idea frontmatter.
+- Doctor auto-fix now supports migrating legacy `cancelled` status to `obsolete`.
+- Doctor auto-fix now supports removing derived `location` from idea frontmatter.
+
+### Technical
+- Added regression tests for legacy status normalization in formatter output.
+- Added validator and fixer tests for `location` cleanup and `cancelled` migration paths.
+
+## [0.13.3] - 2026-03-05
+
+### Changed
+- Updated E2E expectation wording for `ace-idea` move-to-next flow to match current root-scope behavior (no dedicated `_next` directory) and align verification output with `root` scope.
+
+## [0.13.2] - 2026-03-05
+
+### Changed
+- E2E idea-lifecycle expectations were updated for default root-scope behavior (no legacy `_next` relocation requirement).
+
+## [0.13.1] - 2026-03-04
+
+### Fixed
+- Restored backward-compatible legacy `doctor_cli_args` fallback when using nested `idea.doctor.cli_args`.
+
+### Changed
+- Preserved compatibility for legacy codex default shorthand values when normalizing provider CLI args.
+
+## [0.13.0] - 2026-03-04
+
+### Changed
+- Renamed doctor agent CLI argument config from `doctor_cli_args` to nested `doctor.cli_args`.
+- Converted default doctor CLI args for `gemini` to array format.
+
+- Switched default doctor arg values to provider-array format.
+
+## [0.12.4] - 2026-03-03
+
+### Changed
+- Config: replaced `special_folders` map with `special_folder_prefix: "_"` (prefix-based detection replaces hardcoded folder list)
+
+## [0.12.3] - 2026-03-03
+
+### Changed
+- IdeaCreator uses two-tier naming: folder slug (5 words) and file slug (7 words) for concise folders with descriptive filenames
+
+## [0.12.2] - 2026-03-03
+
+### Changed
+- List items: ID, tags, and folder are dimmed for visual contrast with title
+- Attachments only shown in `show` output, no longer in list items
+
+## [0.12.1] - 2026-03-03
+
+### Fixed
+- `IdeaScanner#scan_in_folder("next")` returned no results — root items have `special_folder: nil`, not `"next"`; corrected filter to `r.special_folder.nil?` matching TaskScanner and RetroScanner
+
+## [0.12.0] - 2026-03-03
+
+### Added
+- Colored status symbols in list output: pending (default), in-progress (yellow), done (green), obsolete (dim) — TTY-aware, no color when piped
+- `last_folder_counts` on `IdeaScanner` and `IdeaManager`: exposes per-folder item counts from the full scan for use in stats line
+- `list --help` status legend with ANSI colors matching list output
+
+### Changed
+- Status symbols replaced from emoji (⚪🟡🟢⚫) to Unicode shapes (○▶✓✗) for consistent terminal rendering and colorization support
+- `format_list` and `format_stats_line` accept `global_folder_stats:` parameter, always showing folder breakdown in stats line even when viewing a filtered subset
+
+## [0.11.0] - 2026-03-02
+
+### Added
+- `--move-to` / `-m` option on `update` command: relocate idea to a special folder (archive, maybe, anytime) or back to root (next/root//)
+
+### Changed
+- `update` command now accepts `--move-to` alone (no `--set` required), replacing the standalone `move` command
+
+### Removed
+- Standalone `move` command — use `update --move-to` instead
+- `IdeaManager#move` method — use `IdeaManager#update(move_to:)` instead
+
+## [0.10.0] - 2026-03-02
+
+### Added
+- `--git-commit` / `--gc` flag on `create`, `update`, and `move` commands to auto-commit changes via `ace-git-commit`
+
+## [0.9.0] - 2026-03-02
+
+### Added
+- `status` CLI command showing up-next ideas, summary stats, and recently completed ideas
+- `--up-next-limit` and `--recently-done-limit` options for status command (configurable via config.yml)
+- `IdeaDisplayFormatter.format_status` and `format_status_line` class methods for status overview rendering
+- Config defaults: `status: { up_next_limit: 7, recently_done_limit: 7 }`
+
+## [0.8.0] - 2026-03-02
+
+### Added
+- `IdeaScanner#last_scan_total` exposes total item count before folder filtering
+- `IdeaManager#last_list_total` exposes total item count for "X of Y" stats display
+- `IdeaDisplayFormatter.format_list` and `format_stats_line` accept `total_count:` parameter
+- CLI list command passes total count through to formatter for contextual stats
+
+## [0.7.0] - 2026-03-02
+
+### Added
+- `IdeaDisplayFormatter.format_stats_line` for generating stats summary (e.g., "Ideas: ⚪ 3 | 🟡 1 | 🟢 2 • 6 total • 33% complete")
+- `format_list` now appends a stats summary line after the item list (omitted for empty lists)
+
+## [0.6.0] - 2026-03-02
+
+### Changed
+- `IdeaManager#list` defaults to `in_folder: "next"` — shows only root ideas by default (excludes _archive, _maybe, etc.)
+- `IdeaScanner#scan_in_folder` supports virtual filters ("next" for root-only, "all" for everything)
+- `IdeaCreator` rejects virtual filter names ("next", "all") in `--move-to` option
+- Use `--in all` to see all ideas including special folders (previous default behavior)
+- Remove `next: _next` from default config special folder mappings
+
+## [0.5.0] - 2026-02-28
+
+### Changed
+- `IdeaMover#move` now accepts an optional `date:` keyword argument; when moving to `_archive`, the idea is placed under a B36TS month/week partition (e.g. `_archive/8p/4/{folder}/`) instead of a flat `_archive/` directory
+- `IdeaManager#move` automatically extracts `completed_at` or `created_at` from idea frontmatter and passes it as the archive date, falling back to `Time.now`
+
+## [0.4.2] - 2026-02-28
+
+### Added
+- `doctor_cli_args` configuration map for the `doctor --auto-fix-with-agent` workflow so each provider can define any required CLI args (default maps `gemini` to `yolo`).
+### Fixed
+- `ace-idea doctor --auto-fix-with-agent` now only passes CLI args when the configured map contains an entry, preventing Gemini CLI from receiving unsupported flags while still honoring other providers (tests cover the CLI map lookup).
+
+## [0.4.1] - 2026-02-28
+
+### Added
+- `doctor` command: extended auto-fix support for additional issue types
+  - Auto-fix for missing opening '---' delimiter (prepends proper frontmatter)
+  - Auto-fix for legacy folder naming (generates new b36ts ID and renames folder)
+  - Category folder detection (skips folders with only subdirectories, no files)
+- 16 fixable patterns (up from 14)
+
+### Technical
+- 13 new tests for extended auto-fix functionality (230 total tests)
+
+## [0.4.0] - 2026-02-28
+
+### Added
+- `doctor` command: comprehensive health checks for ideas with auto-fix and agent support
+  - Structure validation (folder naming, spec files, stale backups, empty directories)
+  - Frontmatter validation (delimiters, YAML syntax, required/recommended fields)
+  - Scope/status consistency checks (terminal status in _archive, etc.)
+  - Health score (0-100) based on errors/warnings
+  - `--auto-fix` for safe automatic fixes (14 fixable patterns)
+  - `--auto-fix-with-agent` to launch LLM agent for remaining issues
+  - Output formats: `--json`, `--quiet`, `--verbose`, `--summary`
+  - Filters: `--check (frontmatter|structure|scope)`, `--errors-only`
+  - Other options: `--no-color`, `--dry-run`, `--model`
+- `IdeaValidationRules` atom: pure validation predicates for status, ID, scope consistency
+- `IdeaFrontmatterValidator` molecule: per-file frontmatter validation
+- `IdeaStructureValidator` molecule: directory structure validation
+- `IdeaDoctorFixer` molecule: auto-fix engine with dry-run support
+- `IdeaDoctorReporter` molecule: terminal/JSON/summary formatting
+- `IdeaDoctor` organism: orchestrates all validation checks
+- `doctor_agent_model` config default (`gflash`) for `--auto-fix-with-agent`
+
+### Technical
+- 108 new tests covering all doctor components (230 total tests with v0.4.1 additions)
+
+## [0.3.1] - 2026-02-28
+
+### Fixed
+- Test performance: stub `llm_available?` in LLM-related tests to prevent real API calls (43s → <0.2s)
+
+## [0.3.0] - 2026-02-28
+
+### Changed
+- Refactored `IdeaLoader` to use shared `FrontmatterParser` and `TitleExtractor` from `ace-support-items`
+- Refactored `IdeaFrontmatterDefaults.serialize` to delegate to shared `FrontmatterSerializer`
+- Refactored `IdeaManager` to use shared `FrontmatterParser`, `FrontmatterSerializer`, and `FilterApplier`
+- Updated dependency: `ace-support-items ~> 0.2` (was `~> 0.1`)
+
+### Added
+- `--filter` option on `list` command: `ace-idea list --filter status:pending --filter tags:ux|design`
+- `IdeaManager#list` accepts `filters:` parameter for generic `key:value` filter syntax
+- Supports OR values (`key:a|b`), negation (`key:!value`), and AND across multiple filters
+
+## [0.2.4] - 2026-02-28
+
+### Added
+- E2E test scenario `TS-IDEA-001-idea-lifecycle` with three test cases: TC-001 (create idea), TC-002 (list with filters), TC-003 (move to folder)
+
+### Technical
+- Updated `idea/capture` workflow: corrected done-state description to use `ace-idea move <id> --to archive` + `ace-idea update <id> --set status=done`
+- Updated `idea/prioritize` workflow: replaced `ace-idea reschedule` commands with folder-based `ace-idea move` prioritization
+- Fixed `bin/ace-idea` wrapper to load from `ace-idea/exe/ace-idea` (was incorrectly loading from `ace-taskflow/exe/ace-idea`)
+
+## [0.2.3] - 2026-02-28
+
+### Technical
+- Added explicit `require "json"` to `IdeaLlmEnhancer` (prevents runtime NameError in cold process)
+- Removed unused `DEFAULT_STATUS` / `DEFAULT_LLM_MODEL` constants from `IdeaConfigLoader`
+- Removed redundant inline `require "ace/support/items"` inside `IdeaCreator#generate_slug`
+
+## [0.2.2] - 2026-02-28
+
+### Fixed
+- Path traversal in `--to` / `--move-to` options — boundary check via `File.expand_path` in `IdeaMover#move` and `IdeaCreator#determine_target_dir`
+- YAML serializer now quotes YAML-ambiguous values (`true`, `false`, `null`, numbers)
+- `rebuild_file` uses `IdeaFrontmatterDefaults.serialize` for consistent inline-array format (was: `YAML.dump` block format)
+- `IdeaLlmEnhancer` JSON extraction uses regex to handle LLM preamble before code block
+- `IdeaLoader#list_attachments` filters hidden OS files (`.DS_Store` etc.)
+
+### Added
+- `spec.executables` in gemspec — `ace-idea` binary now installs correctly via `gem install`
+
+## [0.2.1] - 2026-02-28
+
+### Fixed
+
+- Sanitize attachment filenames to prevent path traversal (reject `../` and null bytes)
+- `--root` option in `list` now validates path stays within `root_dir` boundary
+- Atomic file writes in `update_idea_file` using temp file + `File.rename` pattern
+- `gem_root` path calculation corrected (was resolving to `lib/` instead of gem root)
+- `ArgumentError` from clipboard failures caught in `exe/ace-idea` with friendly message
+- TOCTOU race condition in `IdeaMover` replaced with `File.rename` + cross-device fallback
+- Same-path move in `IdeaMover` now returns early (no-op) instead of raising misleading error
+- Config loader rescues only `Errno::ENOENT` / `Psych::SyntaxError` instead of `StandardError`
+- Formatting drift after repeated `update` calls fixed (strip leading newline in `parse_file`)
+- YAML serializer now quotes all YAML special characters (`@`, `*`, `&`, `!`, `%`, `[`, `]`, etc.)
+- CLI `update` command uses `FieldArgumentParser` for type inference (arrays, booleans, numerics)
+
+### Technical
+
+- Regression tests for path traversal (attachment filenames, `--root`), same-path no-op, null bytes
+- Total: 109 tests, 336 assertions, 0 failures
+
+## [0.2.0] - 2026-02-28
+
+### Added
+
+- `ace-idea` CLI executable with 5 commands: `create`, `show`, `list`, `move`, `update`
+- `IdeaCLI` registry (`lib/ace/idea/cli.rb`) following dry-cli Registry pattern
+- `create` command: positional content, `--title`, `--tags`, `--move-to`, `--clipboard`, `--llm-enhance`, `--dry-run`
+- `show` command: display by ref with `--path` and `--content` mode flags
+- `list` command: filter by `--status`, `--tags`, `--in FOLDER`, `--root`
+- `move` command: relocate idea with `--to FOLDER` (short names: archive, maybe, next, root)
+- `update` command: `--set K=V`, `--add K=V`, `--remove K=V` for frontmatter mutation
+- `version` and `help` commands via `ace-support-core` DryCli helpers
+- SIGINT handling with exit code 130 in `exe/ace-idea`
+- `dry-cli ~> 1.0` runtime dependency
+- Handbook workflow instructions moved from `ace-taskflow`: `idea/capture.wf.md`, `idea/capture-features.wf.md`, `idea/prioritize.wf.md`
+- CLI integration tests covering all 5 commands and error paths
+
+## [0.1.1] - 2026-02-28
+
+### Added
+
+- Integration tests covering full create→show→update→move→list roundtrip lifecycle
+- Clipboard edge case tests: empty content, binary data, oversized content, gem unavailable
+- LLM enhancement fallback tests at the manager level
+- Concurrent b36ts ID collision tests (two ideas within the 2-second encoding window)
+- Performance tests verifying scan completes within threshold for 500+ idea collections
+
+### Fixed
+
+- `IdeaCreator` now handles duplicate folder names when two ideas share the same b36ts ID
+  and slug (appends numeric counter `-2`, `-3`, etc. to ensure unique directories)
+
+## [0.1.0] - 2026-02-28
+
+Extracted from `ace-taskflow` v0.42.11 (was `Ace::Taskflow::Idea::*`) into a dedicated gem.
+
+### Added
+
+- Initial release with core operations and model
+- `IdeaIdFormatter` atom for raw 6-char b36ts ID generation (no type markers)
+- `IdeaFilePattern` atom for `.idea.s.md` file glob patterns
+- `IdeaFrontmatterDefaults` atom for frontmatter generation and serialization
+- `Idea` model (Struct) with id, status, title, tags, content, path, file_path, special_folder, created_at, attachments, metadata
+- `IdeaConfigLoader` molecule for config cascade (gem defaults -> user -> project)
+- `IdeaScanner` molecule wrapping DirectoryScanner for `.idea.s.md` files
+- `IdeaResolver` molecule wrapping ShortcutResolver for 3-char suffix shortcuts
+- `IdeaLoader` molecule for loading idea directories with frontmatter parsing and attachment enumeration
+- `IdeaCreator` molecule for full idea creation with clipboard support and LLM enhancement
+- `IdeaLlmEnhancer` molecule with hardcoded 3-Question Brief system prompt
+- `IdeaClipboardReader` molecule for system clipboard capture (text, rich, images)
+- `IdeaMover` molecule for relocating idea folders to special folders
+- `IdeaDisplayFormatter` molecule for terminal output formatting
+- `IdeaManager` organism orchestrating all operations with config-driven root directory
+- Default configuration in `.ace-defaults/idea/config.yml`

data/README.md

@@ -0,0 +1,42 @@
+<div align="center">
+  <h1> ACE - Idea </h1>
+
+  Capture ideas quickly, then shape and organize them for execution.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-idea"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-idea.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
+
+![ace-idea demo](docs/demo/ace-idea-getting-started.gif)
+
+Ideas appear mid-flow: copied from chat, typed in a terminal, or drafted with an LLM. `ace-idea` gives them a stable home in git with sortable IDs and lightweight status updates, so ideas stay actionable instead of scattered across notes and tabs.
+
+## How It Works
+
+1. Capture idea text into a structured markdown artifact with metadata from direct input, stdin, or clipboard.
+2. Refine and organize entries through review-oriented workflows with tags, scoping, and bucket placement.
+3. Promote ready ideas into execution tasks when they pass review.
+
+## Use Cases
+
+**Capture from anywhere** - create an idea from direct text input, stdin, or clipboard content with [`ace-idea create`](docs/usage.md). Add `--llm-enhance` when a rough note needs LLM cleanup, or use `/as-idea-capture` for the full agent-driven workflow.
+
+**Shape and review** - run `/as-idea-review` to turn raw notes into structured entries with clearer scope, tags, and next actions.
+
+**Organize by intent** - move ideas into any named folder you choose (e.g. `_review`, `_big`, `_maybe`) to group them by intent. `_archive` is the only special folder — it partitions by date. Root-level ideas act as the `next` queue.
+
+**Track and maintain** - use [`ace-idea list`](docs/usage.md), `ace-idea show`, and `ace-idea status` for visibility, then run `ace-idea doctor` to detect and repair structure drift.
+
+**Promote to execution** - once an idea is ready, hand it off to [ace-task](../ace-task) and continue with planning and implementation workflows.
+
+---
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/demo/ace-idea-getting-started.tape.yml

@@ -0,0 +1,44 @@
+---
+description: List ideas, create one, mark it done, and archive it
+tags:
+- ace-idea
+- docs
+- getting-started
+settings:
+  font_size: 16
+  width: 960
+  height: 560
+  format: gif
+  env:
+    PROJECT_ROOT_PATH: /home/mc/ace-t.5nx
+scenes:
+- name: Browse existing ideas
+  commands:
+  - type: cd $PROJECT_ROOT_PATH
+    sleep: 1s
+  - type: ace-idea list
+    sleep: 3s
+  - type: ace-idea list --in maybe
+    sleep: 3s
+- name: Capture a new idea
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-idea create 'Nightly regression suite for LLM providers' --tags testing,llm
+    sleep: 3s
+- name: Complete and archive the idea
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-idea list
+    sleep: 3s
+  - type: "DEMO_ID=$(ace-idea list --in next | grep 'LLM provider' | cut -d' ' -f2) && ace-idea update $DEMO_ID --set status=done --move-to archive"
+    sleep: 3s
+- name: Check overall status
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-idea status
+    sleep: 5s
+teardown:
+- run: cd /home/mc/ace-t.5nx && find .ace-ideas -type d -name '*nightly-regression-suite*' -exec rm -rf {} + 2>/dev/null || true

data/docs/demo/fixtures/README.md

@@ -0,0 +1,3 @@
+# Demo fixtures for ace-idea
+
+Seed data used by YAML demo setup.

data/docs/demo/fixtures/sample.txt

@@ -0,0 +1 @@
+sample fixture content

data/docs/getting-started.md

@@ -0,0 +1,102 @@
+---
+doc-type: user
+title: ace-idea Getting Started
+purpose: Tutorial for first-run ace-idea workflows
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Getting Started with ace-idea
+
+This walkthrough shows the core `ace-idea` loop: capture one thought, improve it with clipboard or LLM context,
+organize it, and list what should happen next.
+
+## Prerequisites
+
+* Ruby 3.2+
+* `ace-idea` installed
+* A project directory where you want ideas stored
+* Optional: clipboard support for `--clipboard` — on macOS this works out of the box with rich content (text, RTF, HTML, images via ace-support-mac-clipboard); on Linux or Windows install the `clipboard` gem (`gem install clipboard`) for plain-text clipboard access
+* Optional: LLM provider configuration for `--llm-enhance`
+
+## Installation
+
+```bash
+gem install ace-idea
+```
+
+By default, `ace-idea` stores ideas in `.ace-ideas/` under your current working directory.
+
+## 1. Capture Your First Idea
+
+Start with a direct text capture:
+
+```bash
+ace-idea create "My idea" --title "Feature X"
+```
+
+This creates a new folder inside `.ace-ideas/` with a matching `.idea.s.md` file and a short ID you can use later.
+
+## 2. Capture from Clipboard
+
+When the idea is already copied, skip the paste step:
+
+```bash
+ace-idea create --clipboard
+```
+
+You can also combine clipboard text with a short lead-in:
+
+```bash
+ace-idea create "Dashboard notes" --clipboard
+```
+
+## 3. Ask for LLM Enhancement
+
+If the idea is rough, let `ace-idea` expand it before writing the file:
+
+```bash
+ace-idea create --clipboard --llm-enhance
+```
+
+If enhancement fails, the raw capture is still saved.
+
+## 4. Organize the Idea
+
+Move an idea into your next queue after you review it:
+
+```bash
+ace-idea update q7w --move-to next
+```
+
+`next` is the root-scope queue alias. Use the same command for `maybe`, `anytime`, `archive`, or `root`.
+
+## 5. List What Matters Now
+
+See everything queued for action:
+
+```bash
+ace-idea list --in next
+ace-idea status
+```
+
+`list` is useful for focused filtering. `status` gives you a broader dashboard with up-next items and recently done work.
+
+## Common Commands
+
+| Goal | Command |
+|------|---------|
+| Create a new idea | `ace-idea create "My idea" --title "Feature X"` |
+| Capture from clipboard | `ace-idea create --clipboard` |
+| Enhance clipboard content | `ace-idea create --clipboard --llm-enhance` |
+| Move an idea into the root `next` queue | `ace-idea update q7w --move-to next` |
+| List ideas in the root `next` queue | `ace-idea list --in next` |
+| Show one idea in full | `ace-idea show q7w` |
+
+## Next Steps
+
+* Add metadata with `ace-idea update q7w --set status=in-progress --add tags=research`
+* Run `ace-idea doctor --auto-fix --dry-run` to preview idea hygiene fixes
+* Convert a strong idea into a task with your normal `ace-task` workflow
+* Browse more commands with `ace-idea --help`