Claude Oneshot2001 Omnisight Dev

OMNISIGHT Development Skill

Claude Skill for OMNISIGHT ACAP Development Version: 1.0 Last Updated: November 3, 2025

Skill Purpose

This skill guides Claude through OMNISIGHT-specific development workflows, including ACAP packaging, camera deployment, troubleshooting, and phase management.

Core Principles

1. Camera Compatibility First

ALWAYS check camera compatibility before recommending packages:

Rule: When in doubt, recommend Phase 4 V3 (v0.4.2) - it works on ALL cameras.

2. Package Verification

Before recommending deployment, ALWAYS verify:

# Check package contents
tar tzf <package.eap> | grep -E "omnisight|manifest.json|index.html"

# Must contain:
# - ./omnisight (executable wrapper)
# - ./manifest.json (ACAP manifest)
# - ./html/index.html (web interface)
# - ./package.conf (package config)

3. Log Analysis Protocol

When analyzing deployment issues:

1. Extract error context (10 lines before/after error)
2. Identify error category:
   • Missing file: No such file or directory
   • Missing interpreter: python3: not found
   • Permission: Permission denied
   • Manifest: Failed to convert string to integer
3. Check package version in logs (search for upload.cgi)
4. Verify file installation path: /usr/local/packages/omnisight/
5. Propose specific fix with verification steps

Workflow: Deployment Troubleshooting

Step 1: Analyze Logs

# Search for OMNISIGHT errors
grep -i "omnisight" system_log.txt | grep -E "ERR|WARN"

# Check package upload
grep -i "upload.cgi" system_log.txt | grep ".eap"

# Verify service status
grep -i "sdkomnisight.service" system_log.txt

Step 2: Identify Root Cause

Pattern Recognition:

Step 3: Provide Solution

Template:

## 🔴 Problem Identified

[Clear description of what went wrong]

**Evidence from logs**:

[Relevant log excerpts]

## ✅ Solution

**Deploy**: [Specific package version and location]

**Steps**:
1. [Action 1]
2. [Action 2]
3. [Action 3]

**Expected Result**:
✅ [What should happen]

**Verification**:
- [ ] Check system log for errors
- [ ] Verify service running
- [ ] Confirm "Open" button appears
- [ ] Test web interface

Workflow: Building Packages

Decision Tree

Is this for testing/development?
├─ YES → Use build-stub.sh (fast, no camera needed)
└─ NO → Is Python available on target camera?
    ├─ UNKNOWN → Use build-phase4-v3-native-eap.sh (universal)
    ├─ NO → Use build-phase4-v3-native-eap.sh (native)
    └─ YES → Use build-phase4-v3-native-eap.sh (works on both)

Default Recommendation: ./scripts/build-phase4-v3-native-eap.sh

Build Verification Checklist

After building, ALWAYS verify:

# 1. Package created
ls -lh output/*.eap

# 2. Package size reasonable (>100KB, <500KB for Phase 4)
du -h output/*.eap

# 3. Contains required files
tar tzf output/*.eap | grep -E "omnisight|manifest|html/index.html"

# 4. Manifest is valid JSON
tar xzf output/*.eap manifest.json -O | python3 -m json.tool

# 5. Wrapper script has shebang
tar xzf output/*.eap omnisight -O | head -1
# Should show: #!/bin/sh

Workflow: Documentation Updates

When to Create New Documentation

Critical Issues (always document):

• Deployment failures that took >30 minutes to diagnose
• Camera-specific incompatibilities discovered
• Package bugs affecting multiple users
• Breaking changes in ACAP SDK

Location Mapping:

Critical deployment fix → docs/troubleshooting/deployment-fixes/
User guide → docs/guides/
Phase-specific → docs/phase{1-4}/
ACAP platform info → docs/acap/
Architecture changes → docs/development/

Documentation Template

For Deployment Fixes:

# [Camera Model] [Issue Description]

**Date**: [YYYY-MM-DD]
**Camera Model**: [Model]
**Package Version**: [Version]
**Issue**: [One-line summary]

## Problem Identified

[Detailed description with log evidence]

## Root Cause

[Technical explanation]

## Solution

[Step-by-step fix]

## Prevention

[How to avoid this in future]

## Related Documentation

- [Link to related docs]

Workflow: Phase Management

Phase Status Tracking

Phase 1 (Stub Implementation - 60% complete):

• Focus: Simulation and testing without hardware
• Deliverables: Stub implementations, demo mode
• Build: ./scripts/build-stub.sh

Phase 2 (API Server - 100% complete):

• Focus: Flask REST API with IPC to C core
• Deliverables: Working API endpoints, React dashboard
• Build: ./scripts/deprecated/build-phase2-eap.sh (requires Python)

Phase 3 (Hardware Integration - In Progress):

• Focus: VDO API, Larod API, MQTT swarm
• Deliverables: Real camera integration
• Requirements: Physical camera required

Phase 4 (Claude Flow + Universal Packaging - 100% complete):

• Focus: Distributed AI coordination + Universal builds
• Deliverables: v0.4.2 native package
• Build: ./scripts/build-phase4-v3-native-eap.sh ✅

Phase Transition Checklist

Before moving to next phase:

• All phase deliverables complete
• Tests passing
• Documentation updated
• Package built and tested
• Known issues documented
• Next phase prerequisites verified

Common Patterns

1. Quick Diagnosis

When user reports "no Open button":

# Check these in order:
1. What package version was deployed? (check logs for upload.cgi)
2. Is service running? (check systemd status)
3. Does manifest have settingPage? (check manifest.json)
4. Are files in /usr/local/packages/omnisight/?
5. Any errors in system log?

2. Package Recommendation

When user asks "which package should I use?":

**Recommended Package**: Phase 4 V3 (v0.4.2)

**Location**: `packages/current/OMNISIGHT_-_Precognitive_Security_042_aarch64.eap`

**Why**: Works on all cameras regardless of Python availability

**Camera Compatibility**: Universal ✅
- ARTPEC-8 with Python: ✅ Works
- ARTPEC-8 without Python: ✅ Works
- ARTPEC-9 with Python: ✅ Works
- ARTPEC-9 without Python: ✅ Works

3. Build Script Selection

When user asks "how to build?":

**For deployment**: `./scripts/build-phase4-v3-native-eap.sh`
- Universal compatibility
- No Python dependency
- Includes web interface
- Ready for production

**For testing**: `./scripts/build-stub.sh`
- Fast compilation
- No camera needed
- Demo mode included
- Development only

Error Recovery Patterns

Pattern: Python Not Found

Symptoms:

python3: not found
exit code 127

Immediate Action:

This camera doesn't have Python 3 installed.

✅ **Solution**: Deploy v0.4.2 (Native build)

Package: `packages/current/OMNISIGHT_-_Precognitive_Security_042_aarch64.eap`

This version works without Python.

Pattern: No Such File or Directory (omnisight)

Symptoms:

Failed at step EXEC spawning /usr/local/packages/omnisight/omnisight: No such file or directory

Diagnosis Steps:

1. Check what package was uploaded (version number in logs)
2. Verify package contents: tar tzf <package.eap> | grep omnisight
3. Compare deployed version vs recommended version

Likely Causes:

• Wrong package deployed (check version number)
• Corrupted package (re-download)
• Incomplete installation (reinstall)

Pattern: No "Open" Button

Diagnosis Checklist:

1. **Is service running?**
   - Check toggle status
   - Check system log for crashes

2. **Is settingPage configured?**
   - manifest.json must have: "settingPage": "index.html"

3. **Does index.html exist?**
   - Should be in /usr/local/packages/omnisight/html/

4. **Is package correct version?**
   - v0.4.2 is recommended
   - Check upload.cgi logs for version

5. **Is runMode correct?**
   - Should be "respawn" for web servers
   - "never" won't serve pages

Quick Reference Commands

Package Management

# List package contents
tar tzf <package.eap>

# Extract specific file
tar xzf <package.eap> manifest.json -O

# Check package size
du -h <package.eap>

# Verify manifest JSON
tar xzf <package.eap> manifest.json -O | python3 -m json.tool

Camera Operations (SSH)

# Install package
acapctl install /tmp/<package.eap>

# Start/stop service
acapctl start omnisight
acapctl stop omnisight

# Check status
acapctl status omnisight

# View logs
tail -100 /var/log/messages | grep omnisight

# Uninstall
acapctl uninstall omnisight

Log Analysis

# Find OMNISIGHT errors
grep -i "omnisight" system_log.txt | grep ERR

# Find package upload
grep -i "upload.cgi" system_log.txt | grep ".eap"

# Find Python errors
grep -i "python3: not found" system_log.txt

# Service failures
grep -i "sdkomnisight.service" system_log.txt

Communication Style

When Providing Solutions

DO:

• ✅ Provide specific package version and location
• ✅ Show evidence from logs
• ✅ Include verification steps
• ✅ Explain why the issue occurred
• ✅ Link to relevant documentation

DON'T:

• ❌ Say "try this" without explanation
• ❌ Recommend deprecated packages
• ❌ Skip verification steps
• ❌ Ignore log evidence
• ❌ Give generic answers

Template for Responses

## 🔴 [Problem Summary]

I've analyzed the [logs/screenshot/issue] and identified:

**Evidence**:
[Log excerpts or specific observations]

## ✅ Solution

**[Recommended Action]**

[Specific steps with commands/paths]

## Why This Works

[Brief technical explanation]

## Verification

After deployment:
- [ ] [Check 1]
- [ ] [Check 2]
- [ ] [Check 3]

## Documentation

[Link to relevant docs for details]

Critical Rules

1. Never Recommend Deprecated Packages

Deprecated (Don't recommend):

• ❌ build-phase2-eap.sh (Python required)
• ❌ build-phase4-eap.sh (Python required)
• ❌ build-phase4-fixed-eap.sh (Python required)
• ❌ build-phase4-v2-eap.sh (Python required)

Current (Always recommend):

• ✅ build-phase4-v3-native-eap.sh (Universal)
• ✅ build-stub.sh (Testing only)

2. Always Verify Package Version

Before recommending deployment:

# User reports issue → First check what they deployed
grep "upload.cgi" logs.txt | grep ".eap"
# Extract version number from filename

3. Camera Compatibility Matrix is Gospel

Never guess about Python availability. Reference the compatibility matrix:

• M4228-LVE (ARTPEC-8): Has Python 3 ✅
• P3285-LVE (ARTPEC-9): No Python 3 ❌
• P3265-LVE (ARTPEC-9): No Python 3 ❌
• Unknown: Assume no Python 3 (safest)

4. Documentation Paths Matter

After folder reorganization, ALWAYS use new paths:

OLD: PHASE4_PYTHON_DEPENDENCY_ISSUE.md
NEW: docs/troubleshooting/deployment-fixes/PHASE4_PYTHON_DEPENDENCY_ISSUE.md

OLD: QUICK_TROUBLESHOOTING.md
NEW: docs/troubleshooting/QUICK_TROUBLESHOOTING.md

OLD: ACAP_PACKAGING.md
NEW: docs/acap/ACAP_PACKAGING.md

Success Metrics

Deployment Success

Green Light Indicators:

✅ Service status: Running
✅ System log: No errors for 5+ minutes
✅ "Open" button: Visible in camera web UI
✅ Web interface: Loads and shows v0.4.2
✅ Server type: Shows "Native" (not Python)

Build Success

Green Light Indicators:

✅ Package created: output/*.eap exists
✅ Package size: 200-400KB (Phase 4 range)
✅ Contains files: omnisight, manifest.json, html/
✅ Manifest valid: JSON parses correctly
✅ Wrapper script: Has #!/bin/sh shebang

Troubleshooting Decision Tree

User reports issue
├─ No "Open" button?
│  ├─ Check service running → If not running, check logs
│  ├─ Check package version → If v0.4.0 or v0.4.1, recommend v0.4.2
│  └─ Check manifest → Verify settingPage configured
│
├─ Service won't start?
│  ├─ Check logs for "python3: not found" → Deploy v0.4.2
│  ├─ Check logs for "No such file" → Wrong package, deploy v0.4.2
│  └─ Check permissions → Verify omnisight is executable
│
├─ Web interface doesn't load?
│  ├─ Service running? → If yes, check reverse proxy config
│  ├─ Check html/index.html exists → Should be in package
│  └─ Browser console errors? → May need to rebuild package
│
└─ Which package to use?
   └─ ALWAYS recommend v0.4.2 (works on all cameras)

Skill Activation

This skill is active for all OMNISIGHT-related tasks including:

• Package building
• Deployment troubleshooting
• Log analysis
• Documentation updates
• Camera compatibility questions
• Build script selection
• Phase management

Last Validated: November 3, 2025 (P3265-LVE deployment fix)