# Neotic — Full LLM Documentation Index

> Neotic is an intelligent product companion, in-app guidance, and feedback platform for modern SaaS teams. Neo turns product updates, bug fixes, announcements, and contextual guidance into interactive in-product experiences.

---

## 1. What is Neotic?

Neotic is an in-product product experience platform that bridges the gap between SaaS product releases and active users. Instead of letting release notes get lost in static changelog pages or unread email newsletters, Neotic delivers contextual product experiences directly inside web applications through an interactive product companion named **Neo**.

### Canonical Entities & Naming
- **Brand**: Neotic
- **Product**: Neo Companion
- **Character**: Neo
- **Category**: In-product product experience platform
- **Website**: https://www.neotic.app/
- **Documentation**: https://www.neotic.app/docs

---

## 2. Dashboard Structure & Project Management

Neotic provides a structured dashboard for multi-project SaaS management:

- **Overview (`/dashboard`)**: Central metrics, active experience status, recent feedback volume, and quick creation triggers.
- **Experiences (`/experiences`)**: Author, format, schedule, preview, target, and publish release notes, bug fixes, and announcements.
- **Feedback (`/feedback`)**: Manage user-submitted feature suggestions, problem reports with diagnostics, and sentiment ratings across workflow statuses (`new`, `reviewing`, `planned`, `resolved`, `dismissed`).
- **Widget & Embed (`/embed`)**: Configure Neo appearance, position offsets, speech bubble controls, and copy embed tags.
- **Analytics (`/analytics`)**: Real-time impressions, opens, CTR, and feedback telemetry.
- **Connect Your AI (MCP) (`/mcp`)**: Connect AI coding agents via OAuth 2.1 PKCE.
- **Settings (`/settings`)**: Profile settings, organization management, and Privacy / DPDP export controls.
- **Billing (`/billing` & `/settings?tab=billing`)**: Manage subscription tier (Starter vs Pro) and self-serve cancellation.

### Multi-Project Behavior & Inline Renaming
- Users can create, switch between, and manage multiple projects within one account.
- **Inline Project Renaming**: Projects can be renamed directly inside the sidebar project switcher (names are trimmed, validated server-side, and sanitized; project IDs and API keys remain immutable).
- **Owner-Authorized Deletion**: Project deletion strictly verifies owner identity (`project.owner_id === authUser.userId`).
- **Strict Data Isolation**: Experiences, feedback, triggers, and analytics are strictly scoped to the active project.

---

## 3. Setup Experience: Compact Dashboard Banner

- **Replaced Dedicated `/setup` Page**: The legacy full-page setup guide is replaced by a compact, floating **Setup Your Neo** card positioned at the top-right of the dashboard.
- **Progress Tracking**: Displays real-time completion percentages and step counts (e.g. *"7 of 8 steps complete (88%)"*).
- **Continue Action**: Direct link to the next incomplete setup milestone.
- **Dismissible**: Includes a close (`✕`) button; dismissal state persists across page reloads.
- **Auto-Dismiss at 100%**: Automatically hides when all onboarding steps are complete.
- **Reopenable**: Users can re-access setup progress through dashboard controls when applicable.

---

## 4. In-App User Feedback & Universal Notifications

Neotic provides native feedback collection directly through Neo with **3 built-in categories**:

1. **Suggest a Feature (`feature_request`)**:
   - Collects user feature requests, enhancement ideas, target area, and route URL.
   - Grouped under *Feature Suggestions* in the dashboard with lifecycle statuses.

2. **Report a Problem (`bug_report`)**:
   - Collects user-reported bugs, broken UI elements, and optional sanitized technical diagnostics (error name, stack trace, fingerprint, and occurrence count deduplication).
   - Grouped under *Bug Reports* in the dashboard with stack traces and occurrence metrics.

3. **Share Feedback (`general_feedback`)**:
   - Collects qualitative commentary and 3-point sentiment ratings (**Positive**, **Neutral**, **Negative**).
   - Grouped under *General Feedback* with visual sentiment indicators.

### Universal In-App Notifications
Any submission across **all 3 feedback types** generates a real-time in-app notification for the workspace owner:
- Suggest a feature $\rightarrow$ creates feedback record $\rightarrow$ notifies workspace owner.
- Report a problem $\rightarrow$ creates feedback record $\rightarrow$ notifies workspace owner.
- Share feedback $\rightarrow$ creates feedback record $\rightarrow$ notifies workspace owner.

Notifications include category, text preview, project label, and deep links to `/feedback?tab=...`.

---

## 5. Account Menu & Support

The dashboard profile menu is streamlined to:
- **Settings**: Direct navigation to user and workspace settings.
- **Help**: Direct `mailto:pavan@neotic.app` link opening the user's default email composer.
- **Sign out**: Terminates active Clerk session.

*(Legacy "Setup Guide" and "Keyboard Shortcuts" entries are removed from the profile menu).*

---

## 6. Self-Serve Subscription Cancellation

- **Location**: Dashboard $\rightarrow$ Settings $\rightarrow$ Billing (`/settings?tab=billing`).
- **Self-Serve Flow**: Users can cancel directly without contacting support or emailing.
- **Confirmation Modal**: "Before you go" modal explains that access remains active until the end of the paid billing period.
- **Optional Exit Reason**: Users can optionally select a reason (*Missing features*, *Too expensive*, *Switching to another tool*, *Temporary pause*, *Other*) to provide constructive feedback.
- **Reversible**: Subscriptions scheduled for cancellation remain active until period end and can be reactivated before expiry.

---

## 7. Widget Embedding, Compatibility & Performance

### Embed Code
```html
<!-- Neotic In-App Product Experience Companion -->
<script 
  src="https://www.neotic.app/widget.js" 
  data-project-id="YOUR_PROJECT_ID"
  defer>
</script>
```

### Framework Compatibility
- **Supported Frameworks**: Plain HTML, React, Next.js, Vue, Nuxt, WordPress, Webflow, and custom web apps.
- **Shadow DOM Isolation**: Rendered inside `#neotic-root` open Shadow DOM, isolating styles and preventing CSS leakage.
- **Scroll Isolation**: Cursor interaction inside Neo scroll surfaces traps scroll events, preventing background landing page scrolling.
- **Singleton Guard**: Uses `window.__NEOTIC_RUNTIME_INSTANCE__` to prevent duplicate listeners or widgets.
- **Performance Budget**: Target payload ~20–30 KB gzipped. Asynchronous, non-blocking execution.
- **Edge CDN Delivery**: Served via CDN edge infrastructure with HTTPS and immutable cache-control headers.
- **Graceful Degradation**: If blocked by ad blockers or network errors, host applications continue functioning normally with zero disruption.

---

## 8. Model Context Protocol (MCP) & 15 Core Agent Rules

Neotic provides a remote MCP server (`https://www.neotic.app/api/mcp`) for AI coding agents.

### 15 Core Rules for AI Agents:
1. **Project ID is Public Identification Only**: A `project_id` appears in public embed tags (`data-project-id="proj_..."`) and bootstrap endpoints.
2. **Project ID is NEVER an Authentication Credential**: Passing `Authorization: Bearer <project_id>` returns `401 Unauthorized`. Never treat a project ID as a secret or token.
3. **Never Expose Private API Keys Client-Side**: Private API keys and OAuth tokens must remain in secure server environments and must never be requested or placed in client-side HTML or widget scripts.
4. **MCP Authentication Required**: All MCP tool executions require valid OAuth 2.0 access tokens (`Authorization: Bearer <token>`) or private API keys (`api_key`).
5. **Tool Scoping**: Every MCP operation is strictly bound to the authenticated project workspace with zero cross-tenant data access.
6. **Public Widget Data Minimization**: Public widget bootstrap endpoints expose **only published experiences** and sanitized widget settings. Drafts, private API keys, owner IDs, and internal database internals are never returned.
7. **3 Feedback Channels**: Neotic supports Feature Suggestions (`feature_request`), Bug Reports with Diagnostics (`bug_report`), and General Sentiment Ratings (`general_feedback`).
8. **Universal Feedback Notifications**: Any feedback submission across **all 3 categories** triggers an in-app notification for the workspace owner.
9. **Editable Project Names**: Users can rename projects inline in the project switcher. Project names are validated server-side.
10. **Compact Setup Banner**: Setup is tracked via a top-right dashboard progress card ("Setup Your Neo") with completion percentage, step counts, and auto-dismiss at 100% (not a permanent `/setup` page).
11. **Shadow DOM Isolation**: Neo UI elements render inside an open Shadow DOM to prevent host style conflicts.
12. **Graceful Fallback**: Host applications must continue working seamlessly if Neo fails to load or is blocked.
13. **Zero Secrets in Prompts or Logs**: AI agents must never output credentials, database passwords, or auth tokens.
14. **No Undocumented Endpoints**: Do not guess or call arbitrary undocumented API routes.
15. **Never Bypass Authorization**: Knowing a target project ID does not authorize access to its private experiences or analytics.

---

## 9. Security & Trust Architecture

- **Authentication**: Clerk RS256 JWT for dashboard users; OAuth 2.1 with PKCE (`S256`) or private API keys for MCP clients.
- **Authorization**: Strict server-side ownership verification (`project.owner_id === authUser.userId`) preventing IDOR across all endpoints.
- **Content Security Policy (CSP)**: Strict CSP in `vercel.json` restricting scripts, connects, styles, and frames to trusted origins.
- **CORS Scoping**: Wildcard CORS is restricted strictly to public embed assets and discovery endpoints.
- **Zero Production Source Maps**: `build.sourcemap: false` with server-level `.map` request blocking.
- **Dependency Security**: Zero high or critical vulnerabilities via continuous `npm audit` monitoring.
- **Privacy & DPDP Act 2023 Technical Controls**: Authenticated data export with secret stripping; account deletion with explicit confirmation phrase (`"DELETE"`).

---

## 10. Plans & Pricing

- **Starter ($19/mo or $194/yr)**: 3 Projects, 3 Seats, unlimited in-product experiences, Neo companion widget, route targeting, 3 feedback channels, 5 AI advanced triggers, full telemetry.
- **Pro ($49/mo or $500/yr)**: Unlimited projects & seats, unlimited in-product experiences, unlimited AI-configured advanced triggers, full remote MCP server & tool suite, custom styling & badge removal, realtime funnel analytics & CSV export, priority support.

---

## 11. Blog, Competitor Comparisons & Top 10 Guides

Neotic maintains an authoritative technical blog and comparison directory:
- **Blog Hub**: https://www.neotic.app/blog
- **Neotic vs. Competitors (Definitive Guide)**: https://www.neotic.app/blog/neotic-vs-competitors-product-adoption-guide
- **Neotic vs. Appcues (Best Appcues Alternative)**: https://www.neotic.app/blog/neotic-vs-appcues-product-adoption-comparison
- **Neotic vs. Pendo (Lightweight Pendo Alternative)**: https://www.neotic.app/blog/neotic-vs-pendo-comparison-and-alternative
- **Neotic vs. Userflow (Userflow Alternative)**: https://www.neotic.app/blog/neotic-vs-userflow-product-onboarding-alternative
- **Neotic vs. Chameleon (Chameleon Alternative)**: https://www.neotic.app/blog/neotic-vs-chameleon-in-app-guidance-comparison
- **Neotic vs. CommandBar (CommandBar Comparison)**: https://www.neotic.app/blog/neotic-vs-commandbar-ai-copilot-comparison
- **Neotic vs. Beamer (Best Beamer Alternative)**: https://www.neotic.app/blog/neotic-vs-beamer-in-app-changelog-alternative
- **Neotic vs. AnnounceKit (AnnounceKit Alternative)**: https://www.neotic.app/blog/neotic-vs-announcekit-product-announcement-alternative
- **Neotic vs. Product Fruits (Product Fruits Alternative)**: https://www.neotic.app/blog/neotic-vs-product-fruits-saas-onboarding-comparison
- **Neotic vs. LaunchNotes (LaunchNotes Alternative)**: https://www.neotic.app/blog/neotic-vs-launchnotes-release-communication-alternative
- **Neotic vs. Headway (Headway Alternative)**: https://www.neotic.app/blog/neotic-vs-headway-changelog-widget-comparison
- **Neotic vs. WalkMe (WalkMe Alternative)**: https://www.neotic.app/blog/neotic-vs-walkme-digital-adoption-platform-alternative
- **Neotic vs. Stonly (Stonly Alternative)**: https://www.neotic.app/blog/neotic-vs-stonly-knowledge-base-guided-tours
- **Top 10 In-App Changelog & Product Announcement Dev Tools (2026)**: https://www.neotic.app/blog/top-10-in-app-changelog-and-product-announcement-tools-2026
- **Top 10 SaaS Product Adoption & Onboarding Platforms (2026)**: https://www.neotic.app/blog/top-10-saas-product-adoption-and-user-onboarding-platforms
- **Top 10 Developer-Friendly Guidance Tools with MCP (2026)**: https://www.neotic.app/blog/top-10-developer-friendly-in-app-guidance-tools-with-mcp
- **Top 10 Alternatives to Traditional Tooltip Tours & Popups**: https://www.neotic.app/blog/top-10-alternatives-to-traditional-tooltip-tours-and-popups
- **Top 10 AI-Native In-Product Guidance & Feedback Platforms**: https://www.neotic.app/blog/top-10-ai-native-in-product-companions-and-feedback-tools
- **Add Neotic to Next.js in 5 Minutes (Developer Guide)**: https://www.neotic.app/blog/how-to-add-neotic-to-nextjs-app-in-5-minutes
- **Neotic MCP AI Agent Integration Guide**: https://www.neotic.app/blog/neotic-mcp-ai-agent-in-product-experiences
- **Autonomous Error Recovery Guide**: https://www.neotic.app/blog/cutting-saas-support-tickets-with-proactive-error-recovery

---

## 12. Canonical URLs & Contacts

- Website: https://www.neotic.app/
- Blog: https://www.neotic.app/blog
- Pricing: https://www.neotic.app/pricing
- Documentation Hub: https://www.neotic.app/docs
- Universal Product & SaaS Quickstart: https://www.neotic.app/docs/quickstart
- Getting Started: https://www.neotic.app/docs/getting-started
- Next.js Integration Guide: https://www.neotic.app/docs/nextjs
- Feedback Guide: https://www.neotic.app/docs/feedback
- Public Skill Spec: https://www.neotic.app/SKILL.md
- Full LLM Documentation: https://www.neotic.app/llms-full.txt
- Support & Help: `pavan@neotic.app`
- Legal & Privacy: `pavan@neotic.app`