sap-cap-capire

What this skill does

# SAP CAP-Capire Development Skill

## Related Skills

- **sap-fiori-tools**: Use for UI layer development, Fiori Elements integration, and frontend application generation
- **sapui5**: Use for custom UI development, advanced UI patterns, and freestyle application building
- **sap-btp-cloud-platform**: Use for deployment options, Cloud Foundry/Kyma configuration, and BTP service integration
- **sap-hana-cli**: Use for database management, schema inspection, and HDI container administration
- **sap-abap**: Use for ABAP system integration, external service consumption, and SAP extensions
- **sap-btp-best-practices**: Use for production deployment patterns and architectural guidance
- **sap-ai-core**: Use when adding AI capabilities to CAP applications or integrating with SAP AI services
- **sap-api-style**: Use when documenting CAP OData services or following API documentation standards
- **dependency-upgrade**: Use for secure dependency, lockfile, and supply-chain upgrade controls in CAP service repos

## Table of Contents
- [Quick Start](#quick-start)
- [Project Structure](#project-structure)
- [Core Concepts](#core-concepts)
- [Database Setup](#database-setup)
- [Deployment](#deployment)
- [Bundled Resources](#bundled-resources)

## Quick Start

### Project Initialization
```sh
# Install CAP development kit
npm i -g @sap/cds-dk @sap/cds-lsp

# Create new project
cds init <project-name>
cds init <project-name> --add sample,hana

# Start development server with live reload
cds watch

# Add capabilities
cds add hana          # SAP HANA database
cds add sqlite        # SQLite for development
cds add xsuaa         # Authentication
cds add mta           # Cloud Foundry deployment
cds add multitenancy  # SaaS multitenancy
cds add typescript    # TypeScript support
```

### Basic Entity Example
```cds
using { cuid, managed } from '@sap/cds/common';

namespace my.bookshop;

entity Books : cuid, managed {
  title       : String(111) not null;
  author      : Association to Authors;
  stock       : Integer;
  price       : Decimal(9,2);
}

entity Authors : cuid, managed {
  name        : String(111);
  books       : Association to many Books on books.author = $self;
}
```

### Basic Service
```cds
using { my.bookshop as my } from '../db/schema';

service CatalogService @(path: '/browse') {
  @readonly entity Books as projection on my.Books;
  @readonly entity Authors as projection on my.Authors;
  
  @requires: 'authenticated-user'
  action submitOrder(book: Books:ID, quantity: Integer) returns String;
}
```

## MCP Integration

This skill integrates with the official CAP MCP (Model Context Protocol) server, providing AI agents with live access to your project's compiled CDS model and CAP documentation.

**Available MCP Tools**:
- `search_model` - Fuzzy search for CDS entities, services, actions, and relationships in your compiled CSN model
- `search_docs` - Semantic search through CAP documentation for syntax, patterns, and best practices

**Key Benefits**:
- **Instant Model Discovery**: Query your project's entities, associations, and services without reading files
- **Context-Aware Documentation**: Find relevant CAP documentation based on semantic similarity, not keywords
- **Zero Configuration**: No credentials or environment variables required
- **Offline-Capable**: All searches are local (model) or cached (docs)

**Setup**: See [MCP Integration Guide](references/mcp-integration.md) for configuration with Claude Code, opencode, or GitHub Copilot.

**Use Cases**: See [MCP Use Cases](references/mcp-use-cases.md) for real-world examples with quantified ROI (~$131K/developer/year time savings).

**Agent Integration**: The specialized agents (cap-cds-modeler, cap-service-developer, cap-project-architect, cap-performance-debugger) automatically use these MCP tools as part of their workflows.

## Project Structure
```
project/
├── app/              # UI content (Fiori, UI5)
├── srv/              # Service definitions (.cds, .js/.ts)
├── db/               # Data models and schema
│   ├── schema.cds    # Entity definitions
│   └── data/         # CSV seed data
├── package.json      # Dependencies and CDS config
└── .cdsrc.json       # CDS configuration (optional)
```

## Core Concepts

### CDS Built-in Types
| CDS Type | SQL Mapping | Common Use |
|----------|-------------|------------|
| `UUID` | NVARCHAR(36) | Primary keys |
| `String(n)` | NVARCHAR(n) | Text fields |
| `Integer` | INTEGER | Whole numbers |
| `Decimal(p,s)` | DECIMAL(p,s) | Monetary values |
| `Boolean` | BOOLEAN | True/false |
| `Date` | DATE | Calendar dates |
| `Timestamp` | TIMESTAMP | Date/time |

### Common Aspects
```cds
using { cuid, managed, temporal } from '@sap/cds/common';
// cuid = UUID key
// managed = createdAt, createdBy, modifiedAt, modifiedBy
// temporal = validFrom, validTo
```

### Event Handlers (Node.js)
```js
// srv/cat-service.js
module.exports = class CatalogService extends cds.ApplicationService {
  init() {
    const { Books } = this.entities;
    
    // Before handlers - validation
    this.before('CREATE', Books, req => {
      if (!req.data.title) req.error(400, 'Title required');
    });
    
    // On handlers - custom logic
    this.on('submitOrder', async req => {
      const { book, quantity } = req.data;
      // Custom business logic
      return { success: true };
    });
    
    return super.init();
  }
}
```

### Basic CQL Queries
```js
const { Books } = cds.entities;

// SELECT with conditions
const books = await SELECT.from(Books)
  .where({ stock: { '>': 0 } })
  .orderBy('title');

// INSERT
await INSERT.into(Books)
  .entries({ title: 'New Book', stock: 10 });

// UPDATE
await UPDATE(Books, bookId)
  .set({ stock: { '-=': 1 } });
```

## Database Setup

### Development (SQLite)
```json
// package.json
{
  "cds": {
    "requires": {
      "db": {
        "[development]": { 
          "kind": "sqlite", 
          "credentials": { "url": ":memory:" } 
        },
        "[production]": { "kind": "hana" }
      }
    }
  }
}
```

### Production (SAP HANA)
```sh
cds add hana
cds deploy --to hana
```

### Initial Data (CSV)
- File location: `db/data/my.bookshop-Books.csv`
- Format: `<namespace>-<EntityName>.csv`
- Auto-loaded on deployment

## Deployment

### Cloud Foundry
```sh
# Add CF deployment support
cds add hana,xsuaa,mta,approuter

# Build and deploy
npm install --package-lock-only
mbt build
cf deploy mta_archives/<project>_<version>.mtar
```

### Multitenancy (SaaS)
```sh
cds add multitenancy
```

Configuration:
```json
{
  "cds": {
    "requires": {
      "multitenancy": true
    }
  }
}
```

### Authorization Examples
```cds
// Service-level
@requires: 'authenticated-user'
service CatalogService { ... }

// Entity-level
@restrict: [
  { grant: 'READ' },
  { grant: 'WRITE', to: 'admin' }
]
entity Books { ... }
```

## Bundled Resources

### Reference Documentation (22 files)
1. **references/annotations-reference.md** - Complete UI annotations reference (10K lines)
2. **references/cdl-syntax.md** - Complete CDL syntax reference (503 lines)
3. **references/cql-queries.md** - CQL query language guide
4. **references/csn-cqn-cxn.md** - Core Schema Notation and query APIs
5. **references/data-privacy-security.md** - GDPR and security implementation
6. **references/databases.md** - Database configuration and deployment
7. **references/deployment-cf.md** - Cloud Foundry deployment details
8. **references/event-handlers-nodejs.md** - Node.js event handler patterns
9. **references/extensibility-multitenancy.md** - SaaS multitenancy implementation
10. **references/fiori-integration.md** - Fiori Elements and UI integration
11. **references/java-runtime.md** - Java runtime support
12. **references/localization-temporal.md** - i18n and temporal data
13. **references/nodejs-runtime.md** - Node.js runtime reference
14. **references/plugins-reference.md** - CAP plugins and extensions
15. **references/tools-complete.md** - Complete CLI tools reference
16. **r