@mohammadhprp/system-prompt 0.10.1

package/framework/skills/laravel-best-practices/references/style.md

@@ -0,0 +1,125 @@
+# Conventions & Style
+
+## Follow Laravel Naming Conventions
+
+| What | Convention | Good | Bad |
+|------|-----------|------|-----|
+| Controller | singular | `ArticleController` | `ArticlesController` |
+| Model | singular | `User` | `Users` |
+| Table | plural, snake_case | `article_comments` | `articleComments` |
+| Pivot table | singular alphabetical | `article_user` | `user_article` |
+| Column | snake_case, no model name | `meta_title` | `article_meta_title` |
+| Foreign key | singular model + `_id` | `article_id` | `articles_id` |
+| Route | plural | `articles/1` | `article/1` |
+| Route name | snake_case with dots | `users.show_active` | `users.show-active` |
+| Method | camelCase | `getAll` | `get_all` |
+| Variable | camelCase | `$articlesWithAuthor` | `$articles_with_author` |
+| Collection | descriptive, plural | `$activeUsers` | `$data` |
+| Object | descriptive, singular | `$activeUser` | `$users` |
+| View | kebab-case | `show-filtered.blade.php` | `showFiltered.blade.php` |
+| Config | snake_case | `google_calendar.php` | `googleCalendar.php` |
+| Enum | singular | `UserType` | `UserTypes` |
+
+## Prefer Shorter Readable Syntax
+
+| Verbose | Shorter |
+|---------|---------|
+| `Session::get('cart')` | `session('cart')` |
+| `$request->session()->get('cart')` | `session('cart')` |
+| `$request->input('name')` | `$request->name` |
+| `return Redirect::back()` | `return back()` |
+| `Carbon::now()` | `now()` |
+| `App::make('Class')` | `app('Class')` |
+| `->where('column', '=', 1)` | `->where('column', 1)` |
+| `->orderBy('created_at', 'desc')` | `->latest()` |
+| `->orderBy('created_at', 'asc')` | `->oldest()` |
+| `->first()->name` | `->value('name')` |
+
+## Use Laravel String & Array Helpers
+
+Laravel provides `Str`, `Arr`, `Number`, and `Uri` helper classes that are more readable, chainable, and UTF-8 safe than raw PHP functions. Always prefer them.
+
+Strings — use `Str` and fluent `Str::of()` over raw PHP:
+```php
+// Incorrect
+$slug = strtolower(str_replace(' ', '-', $title));
+$short = substr($text, 0, 100) . '...';
+$class = substr(strrchr('App\Models\User', '\'), 1);
+
+// Correct
+$slug = Str::slug($title);
+$short = Str::limit($text, 100);
+$class = class_basename('App\Models\User');
+```
+
+Fluent strings — chain operations for complex transformations:
+```php
+// Incorrect
+$result = strtolower(trim(str_replace('_', '-', $input)));
+
+// Correct
+$result = Str::of($input)->trim()->replace('_', '-')->lower();
+```
+
+Key `Str` methods to prefer: `Str::slug()`, `Str::limit()`, `Str::contains()`, `Str::before()`, `Str::after()`, `Str::between()`, `Str::camel()`, `Str::snake()`, `Str::kebab()`, `Str::headline()`, `Str::squish()`, `Str::mask()`, `Str::uuid()`, `Str::ulid()`, `Str::random()`, `Str::is()`.
+
+Arrays — use `Arr` over raw PHP:
+```php
+// Incorrect
+$name = isset($array['user']['name']) ? $array['user']['name'] : 'default';
+
+// Correct
+$name = Arr::get($array, 'user.name', 'default');
+```
+
+Key `Arr` methods: `Arr::get()`, `Arr::has()`, `Arr::only()`, `Arr::except()`, `Arr::first()`, `Arr::flatten()`, `Arr::pluck()`, `Arr::where()`, `Arr::wrap()`.
+
+Numbers — use `Number` for display formatting:
+```php
+Number::format(1000000);          // "1,000,000"
+Number::currency(1500, 'USD');    // "$1,500.00"
+Number::abbreviate(1000000);      // "1M"
+Number::fileSize(1024 * 1024);    // "1 MB"
+Number::percentage(75.5);         // "75.5%"
+```
+
+URIs — use `Uri` for URL manipulation:
+```php
+$uri = Uri::of('https://example.com/search')
+    ->withQuery(['q' => 'laravel', 'page' => 1]);
+```
+
+Use `$request->string('name')` to get a fluent `Stringable` directly from request input for immediate chaining.
+
+Use `search-docs` for the full list of available methods — these helpers are extensive.
+
+## No Inline JS/CSS in Blade
+
+Do not put JS or CSS in Blade templates. Do not put HTML in PHP classes.
+
+Incorrect:
+```blade
+let article = `{{ json_encode($article) }}`;
+```
+
+Correct:
+```blade
+<button class="js-fav-article" data-article='@json($article)'>{{ $article->name }}</button>
+```
+
+Pass data to JS via data attributes or use a dedicated PHP-to-JS package.
+
+## No Unnecessary Comments
+
+Code should be readable on its own. Use descriptive method and variable names instead of comments. The only exception is config files, where descriptive comments are expected.
+
+Incorrect:
+```php
+// Check if there are any joins
+if (count((array) $builder->getQuery()->joins) > 0)
+```
+
+Correct:
+```php
+if ($this->hasJoins())
+```

package/framework/skills/laravel-best-practices/references/tailwindcss.md

@@ -0,0 +1,112 @@
+
+# Tailwind CSS Development
+
+## Documentation
+
+Use `search-docs` for detailed Tailwind CSS v4 patterns and documentation.
+
+## Basic Usage
+
+- Use Tailwind CSS classes to style HTML. Check and follow existing Tailwind conventions in the project before introducing new patterns.
+- Offer to extract repeated patterns into components that match the project's conventions (e.g., Blade, JSX, Vue).
+- Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically.
+
+## Tailwind CSS v4 Specifics
+
+- Always use Tailwind CSS v4 and avoid deprecated utilities.
+- `corePlugins` is not supported in Tailwind v4.
+
+### CSS-First Configuration
+
+In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed:
+
+<!-- CSS-First Config -->
+```css
+@theme {
+  --color-brand: oklch(0.72 0.11 178);
+}
+```
+
+### Import Syntax
+
+In Tailwind v4, import Tailwind with a regular CSS `@import` statement instead of the `@tailwind` directives used in v3:
+
+<!-- v4 Import Syntax -->
+```diff
+- @tailwind base;
+- @tailwind components;
+- @tailwind utilities;
++ @import "tailwindcss";
+```
+
+### Replaced Utilities
+
+Tailwind v4 removed deprecated utilities. Use the replacements shown below. Opacity values remain numeric.
+
+| Deprecated | Replacement |
+|------------|-------------|
+| bg-opacity-* | bg-black/* |
+| text-opacity-* | text-black/* |
+| border-opacity-* | border-black/* |
+| divide-opacity-* | divide-black/* |
+| ring-opacity-* | ring-black/* |
+| placeholder-opacity-* | placeholder-black/* |
+| flex-shrink-* | shrink-* |
+| flex-grow-* | grow-* |
+| overflow-ellipsis | text-ellipsis |
+| decoration-slice | box-decoration-slice |
+| decoration-clone | box-decoration-clone |
+
+## Spacing
+
+Use `gap` utilities instead of margins for spacing between siblings:
+
+<!-- Gap Utilities -->
+```html
+<div class="flex gap-8">
+    <div>Item 1</div>
+    <div>Item 2</div>
+</div>
+```
+
+## Dark Mode
+
+If existing pages and components support dark mode, new pages and components must support it the same way, typically using the `dark:` variant:
+
+<!-- Dark Mode -->
+```html
+<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
+    Content adapts to color scheme
+</div>
+```
+
+## Common Patterns
+
+### Flexbox Layout
+
+<!-- Flexbox Layout -->
+```html
+<div class="flex items-center justify-between gap-4">
+    <div>Left content</div>
+    <div>Right content</div>
+</div>
+```
+
+### Grid Layout
+
+<!-- Grid Layout -->
+```html
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+    <div>Card 1</div>
+    <div>Card 2</div>
+    <div>Card 3</div>
+</div>
+```
+
+## Common Pitfalls
+
+- Using deprecated v3 utilities (bg-opacity-*, flex-shrink-*, etc.)
+- Using `@tailwind` directives instead of `@import "tailwindcss"`
+- Trying to use `tailwind.config.js` instead of CSS `@theme` directive
+- Using margins for spacing between siblings instead of gap utilities
+- Forgetting to add dark mode variants when the project uses dark mode

package/framework/skills/laravel-best-practices/references/testing.md

@@ -0,0 +1,43 @@
+# Testing Best Practices
+
+## Use `LazilyRefreshDatabase` Over `RefreshDatabase`
+
+`RefreshDatabase` migrates once per process and wraps each test in a rolled-back transaction. `LazilyRefreshDatabase` skips even that first migration if the schema is already up to date.
+
+## Use Model Assertions Over Raw Database Assertions
+
+Incorrect: `$this->assertDatabaseHas('users', ['id' => $user->id]);`
+
+Correct: `$this->assertModelExists($user);`
+
+More expressive, type-safe, and fails with clearer messages.
+
+## Use Factory States and Sequences
+
+Named states make tests self-documenting. Sequences eliminate repetitive setup.
+
+Incorrect: `User::factory()->create(['email_verified_at' => null]);`
+
+Correct: `User::factory()->unverified()->create();`
+
+## Use `Exceptions::fake()` to Assert Exception Reporting
+
+Instead of `withoutExceptionHandling()`, use `Exceptions::fake()` to assert the correct exception was reported while the request completes normally.
+
+## Call `Event::fake()` After Factory Setup
+
+Model factories rely on model events (e.g., `creating` to generate UUIDs). Calling `Event::fake()` before factory calls silences those events, producing broken models.
+
+Incorrect: `Event::fake(); $user = User::factory()->create();`
+
+Correct: `$user = User::factory()->create(); Event::fake();`
+
+## Use `recycle()` to Share Relationship Instances Across Factories
+
+Without `recycle()`, nested factories create separate instances of the same conceptual entity.
+
+```php
+Ticket::factory()
+    ->recycle(Airline::factory()->create())
+    ->create();
+```

package/framework/skills/laravel-best-practices/references/validation.md

@@ -0,0 +1,75 @@
+# Validation & Forms Best Practices
+
+## Use Form Request Classes
+
+Extract validation from controllers into dedicated Form Request classes.
+
+Incorrect:
+```php
+public function store(Request $request)
+{
+    $request->validate([
+        'title' => 'required|max:255',
+        'body' => 'required',
+    ]);
+}
+```
+
+Correct:
+```php
+public function store(StorePostRequest $request)
+{
+    Post::create($request->validated());
+}
+```
+
+## Array vs. String Notation for Rules
+
+Array syntax is more readable and composes cleanly with `Rule::` objects. Prefer it in new code, but check existing Form Requests first and match whatever notation the project already uses.
+
+```php
+// Preferred for new code
+'email' => ['required', 'email', Rule::unique('users')],
+
+// Follow existing convention if the project uses string notation
+'email' => 'required|email|unique:users',
+```
+
+## Always Use `validated()`
+
+Get only validated data. Never use `$request->all()` for mass operations.
+
+Incorrect:
+```php
+Post::create($request->all());
+```
+
+Correct:
+```php
+Post::create($request->validated());
+```
+
+## Use `Rule::when()` for Conditional Validation
+
+```php
+'company_name' => [
+    Rule::when($this->account_type === 'business', ['required', 'string', 'max:255']),
+],
+```
+
+## Use the `after()` Method for Custom Validation
+
+Use `after()` instead of `withValidator()` for custom validation logic that depends on multiple fields.
+
+```php
+public function after(): array
+{
+    return [
+        function (Validator $validator) {
+            if ($this->quantity > Product::find($this->product_id)?->stock) {
+                $validator->errors()->add('quantity', 'Not enough stock.');
+            }
+        },
+    ];
+}
+```

package/framework/skills/lavish/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: lavish
+description: Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.
+argument-hint: <what the artifact should show>
+author: Kun Chen (kunchenguid)
+---
+
+# Lavish Editor
+
+Lavish Editor helps agents turn rich HTML artifacts into collaborative human review surfaces. Whenever you are about to give user a complex response that will be easier to understand via a rich / interactive page, consider using Lavish Editor. First generate an interactive HTML artifact according to user request, then run `npx -y lavish-axi <html-file>` so the user can visually review it, annotate elements or selected text, queue prompts, and send feedback back through `npx -y lavish-axi poll`.
+
+You do not need lavish-axi installed globally - invoke it with `npx -y lavish-axi <html-file>`.
+If lavish-axi output shows a follow-up command starting with `lavish-axi`, run it as `npx -y lavish-axi ...` instead.
+
+## Request
+
+$ARGUMENTS
+
+If the request above is non-empty, the user invoked `/lavish` explicitly - build an HTML artifact for that request now, following the workflow below.
+If it is empty, infer what to visualize from the conversation.
+
+## When to use
+
+Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop
+
+## Workflow
+
+1. Create the HTML artifact (default location `.opencode/output/lavish/<name>.html` in the working directory).
+2. Run `npx -y lavish-axi <html-file>` to open or resume a review session in the browser.
+3. Run `npx -y lavish-axi poll <html-file>` to long-poll for the user's annotations, queued prompts, and browser-reported `layout_warnings`.
+   The poll stays silent until the user acts or the real browser reports fresh layout warnings - leave it running, never kill it.
+   If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost.
+4. If poll returns `layout_warnings`, fix overflow, clipped text, or overlapping unreadable content and re-check before involving the human.
+5. Apply human feedback, then poll again with `--agent-reply "<message>"` to reply in the browser and keep the loop going.
+6. Run `npx -y lavish-axi end <html-file>` when the review is finished.
+
+## Visual guidance
+
+- Use visual hierarchy to make the most important decisions, risks, tradeoffs, and next actions obvious at a glance
+- Use visual structure such as sections, cards, tables, diagrams, annotated snippets, and side-by-side comparisons instead of long prose
+- Choose typography, spacing, color, and layout deliberately so the artifact has a clear point of view
+- Prevent horizontal overflow at every nesting level: nested grid/flex children also need minmax(0, 1fr) tracks and min-width: 0, especially when badges, labels, or status text use wide pixel or monospace fonts; wrap, truncate, or contain long unbreakable text deliberately
+
+## Playbooks
+
+Run `npx -y lavish-axi playbook <id>` for focused, detailed guidance on any of these.
+One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so read every playbook relevant to your artifact, not just one, for the best quality:
+
+- `diagram` - Map relationships, flows, state, and architecture
+- `table` - Turn dense records into scan-friendly review surfaces
+- `comparison` - Show options, tradeoffs, and current vs target behavior
+- `plan` - Explain a product or technical plan before implementation
+- `code` - Render source code, code files, patches, PR diffs, and before/after code inside Lavish artifacts
+- `input` - Must be used when the agent needs to collect user input on decisions, choices, preferences, triage, scope, or other structured feedback from within the artifact
+- `slides` - Create a deliberate presentation when slides are requested
+
+## Commands & rules
+
+- Run `npx -y lavish-axi <html-file>` to open or resume a Lavish Editor session
+- Unless the user specifies another location, create HTML artifacts in the current working directory under `.opencode/output/lavish/`
+- Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work
+- Run `npx -y lavish-axi poll <html-file>` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix layout_warnings before involving the human. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost
+- Run `npx -y lavish-axi end <html-file>` to end a session
+- Run `npx -y lavish-axi stop` to shut down the background server (it also self-stops when idle or after the last session ends with nothing connected)
+- Run `npx -y lavish-axi playbook <playbook_id>` for focused artifact guidance. One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so read every playbook relevant to the artifact, not just one, for the best quality
+- Lavish does not auto-inject any design system - artifacts stay portable so they render identically when opened directly without lavish-axi running. Before writing any HTML, decide the design direction in this strict priority order, and only move to the next step when the current one truly yields nothing: (1) if the user asked for a specific look or named design system, use that; (2) otherwise you must first inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's design system: Tailwind or theme config, shared CSS variables or design tokens, component library, brand assets, or existing styled pages. If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo; (3) only when both steps come up empty, use the Lavish-recommended Tailwind CSS browser runtime v4 + DaisyUI v5, available via CDN - run `npx -y lavish-axi design` for a copy-pasteable CDN snippet plus component reference, and prefer that CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. When you deliver the artifact, state which of the three design sources you used and why.
+- Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop

package/framework/skills/lavish/examples.md

@@ -0,0 +1,31 @@
+# Lavish Examples
+
+## Example 1: Architecture Diagram
+
+Visualize a proposed microservices migration for team review. Good agent behavior:
+
+- Generate an HTML artifact with a clear SVG or Mermaid diagram showing the current monolith, proposed services, and data flow arrows.
+- Use color coding: blue for existing components, green for new services, orange for shared infrastructure.
+- Include a legend and numbered annotations explaining each architectural decision.
+- Annotate key interfaces and data contracts at each boundary.
+- Run `npx -y lavish-axi <html-file>` to let the team review and leave feedback on specific elements.
+
+## Example 2: Code Diff Comparison
+
+Present a side-by-side comparison of refactored code for review. Good agent behavior:
+
+- Generate an HTML artifact with two panels showing before and after code with syntax highlighting.
+- Highlight changed lines in yellow, added lines in green, removed lines in red.
+- Add inline annotations explaining why each change was made.
+- Include a summary section at the top listing the number of files changed, lines added, and lines removed.
+- Run `npx -y lavish-axi <html-file>` so reviewers can annotate specific code sections.
+
+## Example 3: Performance Benchmark Report
+
+Display benchmark results comparing caching strategies. Good agent behavior:
+
+- Generate an HTML artifact with a bar chart comparing response times across strategies (no cache, Redis, in-memory, database).
+- Include a table with exact measurements: p50, p95, p99 latency, throughput, and memory usage.
+- Add a recommendation section with the preferred strategy highlighted and a rationale.
+- Include interactive tooltips showing sample size and confidence intervals.
+- Run `npx -y lavish-axi <html-file>` so the team can annotate concerns or ask questions about specific benchmarks.

package/framework/skills/notion-mcp/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: notion-mcp
+description: Use this skill when working with the Notion MCP server tools for pages, databases, comments, search, users, and related Notion workflows.
+---
+
+# notion-mcp
+
+Notion MCP server providing 14 tools for interacting with your Notion workspace via the Notion API.
+
+## Tools
+
+| Category         | Tools                                                                                                                                      | Default |
+|------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| Pages (6 tools)  | `fetch`, `create-pages`, `update-page`, `duplicate-page`, `move-pages`, `search`                                                          | yes     |
+| Databases (4)    | `create-database`, `update-data-source`, `create-view`, `update-view`                                                                      | yes     |
+| Comments (2)     | `create-comment`, `get-comments`                                                                                                           | yes     |
+| Users & Teams (2)| `get-users`, `get-teams`                                                                                                                   | yes     |
+
+All tools are available by default — there are no opt-in toolsets for this server.
+
+## Key Workflows
+
+### Page Lifecycle (see references/pages.md)
+
+`fetch` → `create-pages` → `update-page` / `duplicate-page` / `move-pages` → `search`
+
+### Database Schema (see references/databases.md)
+
+`fetch` → `create-database` → `update-data-source` → `create-view` → `update-view`
+
+### Comment Threads (see references/comments.md)
+
+`fetch` (with `include_discussions`) → `create-comment` → `get-comments`
+
+### Search & Discovery
+
+`search` → `fetch` → `get-users` / `get-teams`
+
+## Parameter Hints
+
+- **page_id / database_id**: UUID (with or without dashes) or full Notion URL. Extract from Notion page URLs or from `<page>` / `<database>` tags in fetch output.
+- **data_source_id**: Found in `<data-source url="collection://...">` tags in fetch output. Used for `create-pages`, `update-data-source`, `create-view`.
+- **Markdown content**: Notion-flavored Markdown. Supports inline formatting (bold, italic, code, links), inline math (`$Equation$`), and mention tags (`<mention-date>`, `<mention-user>`, `<mention-page>`, `<mention-database>`). Do not use `@today`, `@name`, `[[page]]` UI shortcuts.
+- **Properties**: JSON map of property names to SQLite values. Date/place properties use expanded key format (e.g., `date:Due:start`, `place:Office:latitude`).
+- **SQL DDL**: Used for `create-database` and `update-data-source` statements. Column names double-quoted, options single-quoted.
+
+## Irreversible Tools
+
+`move-pages` — permanently relocates pages. Cannot be undone programmatically. Use with caution.
+
+## Advanced
+
+- **Enhanced Markdown spec**: Read `notion://docs/enhanced-markdown-spec` through your MCP client's resource reader before writing page content.
+- **View DSL spec**: Read `notion://docs/view-dsl-spec` through your MCP client's resource reader before configuring views.
+- **Templates**: `create-pages` and `update-page` support applying page templates (template IDs shown in `<templates>` section of fetch output).
+- **Multi-source databases**: Some databases have multiple data sources. Use `fetch` to identify the correct `data_source_id`.
+- **Verification**: `update-page` with `update_verification` command supports verifying pages as reviewed (Business/Enterprise plan required).

package/framework/skills/notion-mcp/examples.md

@@ -0,0 +1,31 @@
+# Notion MCP Examples
+
+## Example 1: Create Project Documentation
+
+A new feature needs documentation in the team's Notion workspace. Good agent behavior:
+
+- Use `notion-get-teams` to verify which team space the project docs live in.
+- Use `notion-search` to find the existing project folder page.
+- Use `notion-fetch` on the folder page to understand its structure and available templates.
+- Use `notion-create-pages` with the parent, title, properties, and content matching the folder's page template.
+- Use `notion-create-comment` to notify the team about the new documentation.
+
+## Example 2: Track Bug Reports
+
+A production bug needs to be filed in the team's bug tracking database. Good agent behavior:
+
+- Use `notion-search` to find the bug tracking database.
+- Use `notion-fetch` on the database to see its schema, properties, and available templates.
+- Use `notion-create-pages` with the database parent, filling in title, severity, status, assignee, and reproduction steps.
+- Use `notion-get-users` to look up the correct assignee's user ID.
+- Use `notion-create-comment` on the new bug page to add environment details.
+
+## Example 3: Query Tasks and Update Status
+
+Review all in-progress tasks and update their status. Good agent behavior:
+
+- Use `notion-fetch` on the tasks database to see its views and schema.
+- Use `notion-query-database-view` on the "In Progress" view to filter active tasks.
+- Use `notion-fetch` on each task page URL to review full details.
+- Use `notion-update-page` to transition completed tasks to "Done" with a summary of what was completed.
+- Use `notion-create-comment` on blocked tasks to document the blocker.

package/framework/skills/notion-mcp/references/comments.md

@@ -0,0 +1,112 @@
+# Comments & Discussions
+
+## Overview
+
+Notion supports page-level comments, content-targeted comments on specific blocks, and discussion threads with replies. Use `fetch` with `include_discussions: true` first to see where discussions are anchored, then `get-comments` for full threads.
+
+## Create Comment
+
+### Page-level comment
+
+```
+create-comment
+  page_id: "abc123..."
+  markdown: "Comment with **important** context and a [link](https://example.com)."
+```
+
+### Comment on specific content
+
+Target content by providing a unique start/end snippet:
+
+```
+create-comment
+  page_id: "abc123..."
+  markdown: "This section needs updating."
+  selection_with_ellipsis: "# Meeting No...es heading"
+```
+
+The snippet format: first ~10 characters, `...`, last ~10 characters. Must uniquely identify the content.
+
+### Reply to discussion thread
+
+```
+create-comment
+  page_id: "abc123..."
+  discussion_id: "discussion://pageId/blockId/discussionId"
+  markdown: "Fixed this in the latest update."
+```
+
+Get `discussion_id` from `fetch` (with `include_discussions`) or `get-comments` output.
+
+### Using rich_text instead of markdown
+
+For features that markdown cannot express (mentions, custom emoji, colors):
+
+```
+create-comment
+  page_id: "abc123..."
+  rich_text:
+    - text:
+        content: "Assigned to "
+    - mention:
+        type: "user"
+        user:
+          id: "user-uuid"
+    - text:
+        content: " for review"
+```
+
+### Comment formatting
+
+- **Markdown**: inline formatting only (bold, italic, strikethrough, underline, code, links)
+- **Inline math**: `$Equation$`
+- **Mention tags**: `<mention-date start="2024-12-25"/>`, `<mention-page id="..."/>`, `<mention-user id="..."/>`, `<mention-database id="..."/>`
+- ❌ No block-level markdown (headings, lists, tables, blockquotes) — these render as plain text
+- ❌ No UI shortcuts like `@today`, `@name`, `[[page]]`
+
+## Read Comments
+
+```
+get-comments
+  page_id: "abc123..."
+```
+
+Returns all discussions on the page with full thread content.
+
+### Include child block comments
+
+```
+get-comments
+  page_id: "abc123..."
+  include_all_blocks: true
+```
+
+### Include resolved discussions
+
+```
+get-comments
+  page_id: "abc123..."
+  include_resolved: true
+```
+
+### Get specific discussion by ID
+
+```
+get-comments
+  page_id: "abc123..."
+  discussion_id: "discussion://pageId/blockId/discussionId"
+```
+
+## Workflow
+
+1. `fetch` with `include_discussions: true` — see discussion anchors and `<page-discussions>` summary
+2. `get-comments` with `discussion_id` — read full thread
+3. `create-comment` with `discussion_id` — reply
+4. `create-comment` with `selection_with_ellipsis` — start a new thread on specific content
+5. `create-comment` with just `page_id` — add a general page-level comment
+
+## Limitations
+
+- **No edit/update** — comments cannot be modified after creation
+- **No delete** — comments cannot be removed via this server
+- **No resolution** — cannot mark discussions as resolved via this server