AI Agent

Overview

AI coding assistants can help install Nosmai Effects, build camera interfaces, apply visual packages, add beauty controls, integrate cloud catalogs, and diagnose lifecycle or performance problems. They produce reliable code only when they use the current Nosmai documentation instead of guessing from a generic camera SDK.

Nosmai provides three ways to give an AI assistant accurate product context:

1. the live Nosmai Effects MCP server
2. machine-readable llms.txt documentation
3. a static rules file stored in the application repository

Use the MCP server whenever the AI client supports it. MCP lets the assistant search and read the current Effects documentation on demand. Add the static rules file as a permanent safety and architecture baseline for the project.

What an Effects-aware AI can help with

The documentation covers the complete public integration surface. An AI assistant can use it for:

The AI assistant should still read the focused page for the task. This page defines the integration discipline and routes the assistant to the exact public contract; it does not replace platform API references.

Recommended setup

Use both of these layers:

Live Nosmai Effects MCP
        +
Repository rules file
        |
        v
AI-generated integration
        |
        v
Build and physical-device verification

The MCP server supplies current documentation. The repository rules preserve important decisions such as initialization order, filter coexistence, state ownership, cleanup, and secret handling in every AI session.

Connect the MCP server

Use this endpoint:

https://mcp.nosmai.com/effects

Transport:

Streamable HTTP

The server exposes these documentation tools:

MCP configuration

Clients that accept JSON MCP configuration can use:

{
  "mcpServers": {
    "nosmai-effects": {
      "type": "streamable-http",
      "url": "https://mcp.nosmai.com/effects"
    }
  }
}

Restart the AI client after changing its MCP configuration. The exact settings location differs between editors and desktop clients.

Client setup summary

Do not paste a Nosmai license key into an AI prompt, MCP configuration, issue, or committed rules file.

How the AI assistant should use MCP

Give the assistant this instruction at the beginning of a Nosmai task:

Use the Nosmai Effects MCP server as the primary source of truth.
First list the documentation pages. Search for the feature and platform in
scope, then read every relevant page before proposing or changing code.
Verify the installed Flutter, Android, and iOS versions from the project.
Do not invent APIs, package types, lifecycle behavior, or filter coexistence
rules. Preserve existing app architecture unless the task requires a change.

A reliable assistant workflow is:

1. Call list_effects_pages once to understand the available documentation.
2. Call search_effects_docs with the platform, feature, and error text.
3. Call get_effects_page for every page required by the task.
4. Inspect the application's installed versions and existing integration.
5. Explain the intended change and any compatibility impact.
6. Make the smallest correct change.
7. Run static checks and platform builds.
8. Test camera behavior on a physical arm64 device.

For example, an Android cloud filter task normally requires the cloud filter, Android platform, filter rules, lifecycle, and error pages. A Flutter Agora task also requires the dedicated Flutter Agora guide and its strict setup and teardown order.

Machine-readable documentation

Clients without MCP support can read:

https://nosmai.com/llms.txt
https://nosmai.com/llms-full.txt

Use llms.txt for a compact index. Use llms-full.txt when the assistant needs the complete documentation in one source.

The live MCP server is preferred because it can search and return only the pages relevant to the current task. The llms files are useful for tools that cannot connect to MCP or for building a private documentation index.

Source-of-truth priority

When sources disagree, the AI assistant should use this order:

1. the current Nosmai Effects MCP documentation
2. the platform and release documentation for the installed SDK version
3. https://nosmai.com/llms-full.txt
4. the repository's Nosmai AI rules file
5. old sample code, previous chat messages, or cached AI knowledge

The application source still determines which SDK versions are actually installed. An assistant must not silently upgrade a native SDK, Flutter package, Gradle plugin, CocoaPod, Agora package, or deployment target while solving an unrelated task.

Documentation map

Use the smallest set of pages that completely covers the task. Complex camera or streaming changes usually need more than one page.

Search the MCP documentation when the task spans multiple topics or when an exact method, callback, enum, error, or lifecycle rule is uncertain.

Current public release contract

These products are versioned separately:

The Flutter package does not contain the proprietary Android AAR. A Flutter Android application downloads the current AAR separately, verifies its checksum, renames it to nosmai-release.aar, and places it at:

android/app/libs/nosmai-release.aar

The Flutter iOS integration resolves NosmaiCameraSDK through CocoaPods. Do not manually add a second iOS framework to the same Flutter application.

Always verify the release and compatibility page before changing a version.

Ready-made repository rules

Save the rules below in the location used by the AI client:

For Cursor, wrap the rules with the metadata required by the installed Cursor version. The rule content itself can remain the same.

# Nosmai Effects integration rules

## Authoritative documentation

- Use the live Nosmai Effects MCP server at `https://mcp.nosmai.com/effects`.
- Use `list_effects_pages`, `search_effects_docs`, and `get_effects_page` before
  changing a Nosmai integration.
- If MCP is unavailable, use `https://nosmai.com/llms-full.txt`.
- Verify every public method against the documentation and installed SDK.
- Never invent a Nosmai class, method, enum, package type, callback, or return
  value.
- Preserve the application's current dependency versions unless an upgrade is
  explicitly requested.

## Supported release baseline

- Flutter package: `nosmai_camera_sdk` 3.0.6.
- Android native SDK: 3.0.1, API 21+, `arm64-v8a`, Java 11.
- iOS native SDK: 3.0.0, iOS 15+, physical arm64 device.
- Cloud catalog schema: 2.0.0.
- Flutter Android uses an externally supplied AAR named
  `android/app/libs/nosmai-release.aar`.
- Flutter iOS resolves `NosmaiCameraSDK` through CocoaPods.
- Native SDK and Flutter package versions are independent. Do not assume that
  matching version numbers are required.

## License and initialization

- A license is bound to the configured application identity, platform, enabled
  features, and license policy.
- Initialize Nosmai exactly once through the application's single SDK owner.
- Await the initialization result before opening the camera, configuring it,
  listing protected content, or calling an effect API.
- Flutter must call `WidgetsFlutterBinding.ensureInitialized()` and await
  `NosmaiFlutter.initialize(licenseKey)` before creating the camera screen.
- Android should initialize `NosmaiSDK` once from the Application or another
  process-wide owner before starting camera processing.
- iOS must await the `NosmaiCore` initialization completion before attaching or
  starting the camera.
- Do not initialize the SDK independently from multiple widgets, activities,
  fragments, view controllers, or services.
- Do not block the main thread while waiting for network verification.
- Retry only bounded transient network failures. Do not retry an invalid key,
  expired license, package mismatch, platform mismatch, unsupported version,
  or entitlement failure in a loop.
- Never commit, print, upload, or send the complete license key to analytics.

## Two visual feature families

Nosmai has two related but different visual systems:

1. Protected `.nosmai` packages obtained from local or cloud catalogs.
2. Built-in beauty, makeup, reshape, eye color, hair, and color controls.

- Apply all four `.nosmai` package types through the documented unified
  `applyEffect(path)` flow.
- Do not select a lower-level renderer based on the filename.
- Built-in controls are not `.nosmai` packages and are not returned by the
  local or cloud package list.
- Apply built-in controls with their documented direct SDK methods.
- A packaged `beauty_effect` is not the same as built-in beauty.

## Protected package rules

Every `.nosmai` package declares one canonical type:

- `filter`: full-frame color or visual style.
- `effect`: AR, tracked, animated, or interactive visual.
- `beauty_effect`: packaged makeup or beauty look.
- `background`: packaged background visual.

The package manifest is authoritative. The filename, display name, catalog tab,
or download URL does not determine the package type.

- Do not open, edit, unpack, rewrite, or infer the contents of a protected
  `.nosmai` package.
- Do not expose a protected local package path in user-facing errors or logs.
- Apply a package asynchronously and mark it selected only after its apply
  completion succeeds.
- Use the SDK's active state as the source of truth after apply and removal.

## Package coexistence and replacement

- Only one external `filter` package is active. A new `filter` replaces it.
- Only one external `background` package is active. A new `background`
  replaces it.
- `effect` and `beauty_effect` share one AR package position. Applying either
  replaces the active package in that position.
- A regular external `filter` can normally coexist with one `effect` or
  `beauty_effect`, one background, and built-in beauty.
- A `beauty_effect` can normally coexist with a regular external `filter` and
  a background.
- Built-in beauty, makeup, reshape, eye color, hair, or built-in color mode and
  an external `effect` or `beauty_effect` are mutually exclusive. The latest
  successfully applied mode clears the other through SDK rules.
- Some AR packages own or control their background. Their manifest behavior can
  replace or override a separately selected background.
- Do not manually clear the previous package before applying another package of
  the same type. The successful new apply performs the replacement.
- Never duplicate SDK conflict rules in UI-only state.

## Active state and interface behavior

- Subscribe to the platform's active effects or pipeline state listener.
- Read the current state once when the camera interface is created.
- Update selected cells, tabs, badges, and clear buttons from SDK state and
  successful operation completions, not from tap intent.
- An item can be selected only after apply success and state confirmation.
- A second tap on an active item should call the correct narrow removal method.
- A failed or replaced item must not remain visually selected.
- Remove or cancel listeners when their owner is disposed or destroyed.
- Do not mutate SwiftUI, Flutter, or Android view state synchronously during a
  render or view update callback. Schedule state delivery on the UI thread at a
  safe point and suppress duplicate values.

## Correct removal scope

- To remove one package, use its typed package removal or the narrow clear for
  its active position.
- To clear only the regular external filter, use `clearFilter`.
- To clear only the AR package position, use `clearAREffect`.
- To remove all external packages, use the documented external-package reset.
- Use the full visual reset only when the product action means reset everything.
- Do not use a full reset to remove lipstick, one background, or one filter.
- Removing a downloaded cloud package from cache does not automatically clear
  an already active visual. Clear the active visual separately when required.

## Built-in beauty and makeup

Supported groups include skin and detail controls, lipstick, eyeshadow,
blusher, eyelash, eyebrow, face shaping, eye color, and documented color or
hair controls.

- Use normalized public strengths documented for the selected API.
- Keep slider display values separate from any product-specific internal cap.
- For continuous sliders, update the existing control strength. Do not reload a
  style or package on every slider event.
- Makeup layers such as lipstick, eyeshadow, blusher, eyelash, and eyebrow can
  be combined unless the documentation for a specific mode says otherwise.
- Remove one makeup layer with its matching remove method.
- Remove all makeup with the platform's all-makeup method.
- Reset face-shaping values through the documented morph reset.
- Remove eye color through the dedicated eye-color or eye-lens method.
- Reset skin and detail controls through the built-in filter reset.
- Use the all-beauty reset only when all built-in beauty state should be
  cleared.
- Natural presets should use conservative default strengths and expose an off
  state.
- Do not store a UI item as active solely because its last requested strength
  was greater than zero. Confirm state through the SDK where supported.

## Local package catalog

- Call the documented local package API only after initialization succeeds.
- Use returned metadata and canonical type to build Filter, Effects, Beauty,
  and Background sections.
- Do not hard-code package type from a file suffix or folder name.
- Deduplicate by the stable package identifier supplied by the SDK.
- Keep list work and file work off the UI thread.
- Handle an empty list as a valid interface state unless the SDK reports an
  error.

## Cloud package catalog

Use these API category values:

- `filter` for regular filters.
- `effects` for AR effects.
- `beauty_effect` for packaged beauty looks.
- `bg` for background packages.

- Keep the cloud schema version independent from mobile SDK versions.
- Paginate with the documented page and limit fields.
- Merge pages by `cloudIdentifier` to prevent duplicate cells.
- Use `cloudIdentifier`, not the catalog record `id`, for download and cache
  operations.
- A category-specific or paginated response is not the full server catalog. Do
  not use it to delete cached packages from other categories or pages.
- Track separate states: not downloaded, downloading, downloaded, applying,
  selected, and failed.
- Allow only one in-flight download or apply operation per cloud identifier.
- Reuse or ignore repeated taps while that item is busy.
- Download first, validate the returned local path, then call
  `applyEffect(localPath)`.
- Mark the item selected only after apply succeeds.
- If a sheet closes during download, let the cache-safe work finish but do not
  update a disposed UI owner.
- A completed download may remain cached for the next screen.
- Display retry for recoverable failures without losing already loaded pages.
- Do not expose authorization headers, backend payloads, signed URLs, license
  keys, tokens, or private local paths in UI messages or production logs.

## Camera and preview lifecycle

- Use one camera owner and one Nosmai preview for a camera session.
- Request camera permission before starting capture.
- Request microphone permission only for audio recording or streaming.
- Request photo-library permission only when saving media requires it.
- Do not start a second camera capture session behind the Nosmai preview.
- Avoid destroying and recreating the SDK for a normal route transition.
- When a preview remains mounted, pause and resume it through the documented
  lifecycle methods.
- When the preview leaves the tree or controller hierarchy, release its camera
  ownership and listeners.
- Use the SDK's complete cleanup only when the application is finished with the
  SDK, not on every widget or view-controller disposal.
- Handle application background and foreground transitions.
- Stop capture and release resources in the documented order.
- Test camera switching, repeated entry and exit, interruptions, permission
  denial, and recovery.

## Capture, recording, and gallery input

- Wait for the preview to become ready before enabling capture controls.
- Prevent repeated capture or recording-start requests while one is pending.
- Record the processed Nosmai output when the product promises filters in the
  saved media.
- Keep microphone state and permission independent from camera permission.
- Stop recording and await its result before tearing down the camera owner.
- Validate output existence before showing a success message.
- For gallery or external input, use only the documented platform flow. Do not
  pass an arbitrary file to a camera-only API.
- Preserve image orientation, mirroring, color format, timestamp, and buffer
  ownership rules.

## Live streaming

- Publish Nosmai's processed output, not a second raw camera source.
- Use a single owner for capture, processing, and publishing lifecycle.
- Prefer GPU texture output on Android when the streaming bridge supports it.
- Keep only the newest frame when a CPU consumer is busy.
- On iOS, follow the documented `CVPixelBuffer` ownership rules and do not retain
  a buffer beyond the callback unless it is explicitly retained and released.
- Apply or change effects through the same SDK state while streaming.
- Stop the publisher before clearing Nosmai output callbacks and releasing
  camera or graphics resources.
- For the Flutter Agora bridge, call `getNativeHandle` before
  `NosmaiFlutter.initialize`, create Agora with the shared native handle, and
  follow the documented platform-specific teardown order.
- Do not reorder EGL, engine, Nosmai, channel, and disposal steps from memory.
  Read the current Agora guide first.

## Off-screen and external-frame processing

- Do not run the normal camera preview and an external-frame pipeline against
  the same source unless the documented architecture explicitly requires it.
- Give every input frame one clear owner.
- Respect pixel format, plane stride, orientation, mirroring, and timestamp
  requirements.
- Keep output callbacks lightweight and bounded.
- Prefer stable input dimensions and avoid allocation for every frame.
- Release callbacks, textures, surfaces, and retained buffers in the documented
  cleanup order.
- Flutter does not automatically expose every native off-screen API. Do not
  invent a Dart wrapper; verify current Flutter support first.

## Performance

- Use a physical arm64 device for camera, tracking, recording, and performance
  tests.
- Target the documented default real-time processing rate unless the product
  has measured evidence for a different rate.
- Never perform package parsing, cloud networking, file copying, image decoding,
  or large list processing on the UI thread.
- Do not initialize face tracking, the camera, or the SDK more than once.
- Do not reapply the same package every frame or every widget rebuild.
- Coalesce high-frequency slider updates where necessary.
- Keep one latest frame instead of building an unbounded queue.
- Prefer GPU paths and avoid repeated CPU-to-GPU or color-space conversions.
- Measure first launch, steady-state FPS, frame-to-effect alignment, CPU, GPU,
  memory, thermal behavior, and repeated camera navigation.
- A smooth preview alone is not sufficient. Verify recorded and streamed output.

## Errors and recovery

- Treat every initialize, list, download, apply, capture, recording, and stream
  operation as fallible.
- Map technical SDK errors to concise user-facing messages.
- Keep technical detail in privacy-safe diagnostics, not in the user message.
- Preserve the previous selected visual if a replacement fails.
- Do not show an item as selected before apply success.
- Do not retry permanent license, identity, entitlement, or version errors.
- Use bounded retry and backoff only for transient network failures.
- A black preview requires lifecycle, camera ownership, surface, permission,
  graphics-context, and active-package checks. Do not assume it is always a
  license problem.
- A delayed face effect requires frame scheduling, queue depth, timestamp,
  orientation, and processing-load checks. Do not hide it by increasing UI
  delay.

## Security and production logging

- Nosmai camera frames are processed on device unless the application separately
  sends them to its own network or streaming service.
- Cloud catalog and license requests do not require uploading camera frames.
- Never log complete license keys, access tokens, API responses containing
  private values, signed download URLs, local protected-package paths, user
  identifiers, or live-stream channel tokens.
- Keep verbose SDK and graphics diagnostics disabled in production.
- Production logs may report a high-level initialization or license status and
  privacy-safe error category required for support.
- Do not weaken package protection, signature verification, license checks, or
  entitlement checks to make a test pass.
- Do not unpack, modify, redistribute, or reverse engineer proprietary SDK
  artifacts or `.nosmai` packages.

## Platform-specific requirements

### Flutter

- Await `NosmaiFlutter.initialize` before any instance method.
- Build the camera with `NosmaiCameraPreview` and handle its ready and error
  callbacks.
- Keep subscriptions and asynchronous UI updates safe after widget disposal.
- Do not bundle the Android AAR inside the pub.dev package.
- Ensure the host app provides `android/app/libs/nosmai-release.aar`.
- Let CocoaPods resolve the iOS native SDK.

### Android

- Use API 21 or later, Java 11, and `arm64-v8a` for the current distribution.
- Verify the downloaded AAR against `SHA256SUMS` before integration.
- Initialize once before `startProcessing` or any effect API.
- Keep Camera2 and render-surface lifecycle under one owner.
- Perform cloud and file operations away from the main thread.
- Remove pipeline listeners and release owned executors with their screen.

### iOS

- Use iOS 15.0 or later on a physical arm64 device.
- Open the `.xcworkspace` after CocoaPods installation.
- Await `NosmaiCore` initialization before camera setup.
- Deliver interface state changes on the main thread without mutating SwiftUI
  state during a view update.
- Respect Core Video, Core Media, Metal, and Core Animation thread and ownership
  requirements.
- Disable verbose debug logging before production distribution.

## Verification before completion

- Confirm the SDK initializes once and the camera opens after success.
- Confirm no license key, token, signed URL, private path, or raw payload is
  printed.
- Test every relevant package type: `filter`, `effect`, `beauty_effect`, and
  `background`.
- Test replacement and coexistence rules in both application orders.
- Test built-in beauty after AR, and AR after built-in beauty.
- Test narrow removal, repeated removal, and full reset.
- Test cloud pagination, duplicate prevention, repeated taps, cached apply,
  failed download, retry, and closing the sheet during download.
- Test active-state UI after apply success, apply failure, automatic replacement,
  and removal.
- Test camera switch, background and foreground, repeated screen entry, capture,
  recording, and streaming when used.
- Test first launch and a later cached launch on supported physical Android and
  iOS devices.
- Run the platform analyzer, build, and automated tests without changing
  unrelated dependencies.
- Report what was verified and what still requires manual device testing.

Task prompt template

Use this template when asking an AI assistant to implement or debug a feature:

Use the Nosmai Effects MCP server before changing code.

Project platform and versions:
- Platform: <Flutter, Android, or iOS>
- Nosmai version: <installed version>
- Minimum OS: <current project value>

Task:
<describe the required result>

Required behavior:
- Preserve existing camera, filter, recording, and streaming behavior.
- Follow Nosmai package coexistence and narrow removal rules.
- Use SDK active state as the interface source of truth.
- Handle initialization, permissions, async failure, repeated taps, lifecycle,
  cleanup, and disposed-screen updates.
- Do not expose secrets or protected package paths.

Before implementation:
1. List and search the Nosmai Effects documentation.
2. Read every page needed for this platform and task.
3. Inspect the installed dependency versions and current integration.
4. Explain the root cause or intended architecture in simple wording.

After implementation:
1. Run static checks and a platform build.
2. List physical-device test scenarios.
3. Report changed files, compatibility impact, and any unverified behavior.

Useful task-specific prompts

Build a cloud filter sheet

Use the Nosmai Effects MCP pages for cloud filters, filter rules, lifecycle, and
my platform. Build a paginated sheet with All, Filters, Effects, Beauty, and
Background tabs. Deduplicate by cloudIdentifier, serialize work per item, show
download and apply progress, survive sheet dismissal, apply only a validated
local path, and derive selection from SDK active state.

Build a beauty panel

Use the Nosmai Effects beauty and filter-rules pages. Create sections for skin
and detail, makeup, face shaping, and eye color. Use the documented strength
ranges, update intensity without reloading styles, preserve compatible layers,
use narrow removal, and synchronize every selected control with SDK state.

Diagnose a black preview

Use the Nosmai Effects platform, lifecycle, errors, and streaming pages. Trace
initialization, permission, camera ownership, preview attachment, graphics
context, frame source, active package, background transition, and cleanup order.
Identify evidence for the root cause before changing code. Do not treat native
framework diagnostics as the cause without a matching failure path.

Diagnose filter delay or vibration

Use the Nosmai Effects performance, off-screen, platform, and error pages.
Inspect timestamps, queue depth, latest-frame policy, orientation, mirroring,
camera/output FPS, thread ownership, repeated applies, and CPU/GPU conversions.
Measure the issue on a physical device and preserve the existing public API.

Add filtered live streaming

Use the Nosmai Effects native or Flutter Agora streaming guide and all linked
lifecycle pages. Publish processed Nosmai output, preserve the documented
graphics-context setup, apply filters through normal SDK state, and implement
the exact platform teardown order. Test a second stream in the same app session.

Review AI-generated code

Do not accept AI-generated camera code only because it compiles. Review it against this checklist:

API accuracy

• Every Nosmai symbol exists in the installed public SDK.
• The selected method belongs to the correct platform and version.
• All asynchronous results and errors are handled.
• No native-only API was invented in Flutter.

Visual behavior

• Package type comes from SDK metadata.
• Coexistence and automatic replacement follow SDK rules.
• Built-in beauty and AR switching works in both directions.
• The selected interface matches current SDK active state.
• Removal affects only the intended visual position.

Cloud behavior

• The request uses the correct category value.
• Pagination does not remove unrelated cache entries.
• Download and apply are different states.
• Repeated taps do not start duplicate downloads.
• Closing a screen cannot update disposed interface state.

Camera behavior

• Initialization completes before camera work begins.
• Only one component owns the camera and preview session.
• Background and foreground transitions are handled.
• Recording and streaming publish processed frames.
• Cleanup order allows the camera or stream to start again.

Production behavior

• First launch does not block the UI thread.
• High-frequency slider updates do not reload assets.
• No unbounded frame queue or repeated conversion was added.
• Secrets and protected paths are absent from logs and source control.
• Physical-device testing covers all changed flows.

Common AI mistakes

An AI assistant must not:

• call a Nosmai API before initialization succeeds
• initialize the SDK again from every camera screen
• infer package type from a filename
• treat beauty_effect as built-in beauty
• assume effect and beauty_effect can coexist
• manually clear compatible visual positions before every apply
• update selected UI immediately on tap
• use a full reset for one lipstick, background, or filter action
• confuse cloud record id with cloudIdentifier
• delete the complete cloud cache after one paginated response
• download the same package multiple times after rapid taps
• update a disposed widget or closed sheet
• process cloud files or large lists on the main thread
• create a second raw camera for live streaming
• keep every processed frame in a queue
• change platform dependency versions without permission
• expose license keys, signed URLs, local package paths, or internal payloads
• unpack or modify protected SDK and .nosmai artifacts

Keep the rules current

A copied rules file is a static snapshot. Before a release, migration, or major integration change:

1. reconnect the live MCP server
2. verify the current release and compatibility page
3. review the relevant platform and feature pages
4. update the repository rules only where the documented contract changed
5. rebuild and test on supported physical devices

MCP and the public documentation remain the source of truth. Repository rules help an AI assistant stay consistent, but they do not replace release notes, platform build requirements, or physical-device verification.