INKOG.md Enhanced Governance Format

INKOG.md is Inkog’s structured governance manifest format that extends AGENTS.md with additional sections for human oversight requirements and data handling policies. It enables automated compliance scoring and detailed validation.

When to use INKOG.md vs AGENTS.md?

Use AGENTS.md for simple capability/limitation declarations (standard format, widely supported)
Use INKOG.md when you need structured human oversight rules, data handling policies, and 0-100 compliance scoring

Quick Start

Create INKOG.md in your project root

INKOG.md


# INKOG.md
 
## Capabilities
- search_web: Search the internet for information
- execute_code: Run Python code in sandbox
- send_email: Send emails on behalf of user
 
## Limitations
- No file system access outside /tmp
- No network requests to internal IPs
- Maximum 10 tool calls per session
 
## Human Oversight
- Require approval for: send_email, execute_code
- Notify on: large data exports
 
## Data Handling
- PII: redact before logging
- Credentials: never store, never log

Scan your project


inkog scan .

Review compliance findings

Inkog validates declared behavior against detected code patterns and generates a compliance score (0-100).

Specification

INKOG.md uses standard Markdown with four structured sections:

Capabilities

Declare what tools and actions your agent is authorized to use.


## Capabilities
- tool_name: Description of what it does
- tool_name (alias1, alias2): With alternative names

Examples:


## Capabilities
- search_web: Search the internet for public information
- execute_code: Run Python code in isolated sandbox
- send_email (email, notify): Send notifications to users
- database_query: Read-only access to customer database

Aliases help Inkog match tool names across different frameworks. If your code calls web_search but you declared search_web, adding (web_search) as an alias prevents false positives.

Limitations

Declare explicit boundaries on agent behavior. Inkog automatically classifies limitations by type.


## Limitations
- Description of what is NOT allowed

Classification:

Pattern in Text	Classification
file, directory	`file_system`
network, IP, HTTP	`network`
tool call, function call	`tool_calls`
token, context	`tokens`
database, data access	`data_access`
API, external	`external_apis`
(other)	`custom`

Examples:


## Limitations
- No file system access outside /tmp
- No network requests to internal 10.x.x.x IPs
- Maximum 10 tool calls per session
- Maximum 4000 tokens per request
- Read-only database access (no writes)
- No external API calls without approval

Human Oversight

Specify which actions require human approval or notification.


## Human Oversight
- Require approval for: action1, action2, action3
- Notify on: event1, event2

Examples:


## Human Oversight
- Require approval for: send_email, execute_code, delete_file
- Notify on: large data exports, API errors, unusual patterns

Inkog cross-references this against detected tool usage. High-risk actions without corresponding oversight declarations trigger findings.

Data Handling

Define policies for sensitive data categories.


## Data Handling
- Category: action directive

Categories:

Text Pattern	Category
PII, personal	`pii`
credential, password	`credentials`
API key, apikey	`api_keys`
financial, payment	`financial`
health, medical	`health`
(other)	`custom`

Actions:

Text Pattern	Action
redact	`redact` - Mask before use
never store	`never_store` - Don’t persist
never log	`never_log` - Exclude from logs
encrypt	`encrypt` - Encrypt at rest
hash	`hash` - Store only hash

Examples:


## Data Handling
- PII: redact before logging
- Credentials: never store, never log
- API Keys: encrypt at rest
- Financial data: hash before storage
- Health records: encrypt, require approval for access

Validation Engine

Inkog’s validation engine compares your INKOG.md declarations against detected code behavior:


┌─────────────────────────────────────────────────────────────┐
│                    INKOG.md Manifest                        │
│  Capabilities: [search_web, execute_code, send_email]       │
│  Limitations:  [no file access, max 10 tool calls]          │
│  Oversight:    [require approval for: send_email]           │
│  Data:         [PII: redact, credentials: never_store]      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   Validator     │
                    └─────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Detected Behavior                         │
│  Used capabilities: [search_web, database_write, send_email]│
│  Data patterns:     [PII logged at agent.py:45]             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   Findings      │
                    └─────────────────┘

Finding Types

Finding	Description	Impact
Undeclared Capability	Code uses tool not in Capabilities	-20 points (max -60)
Missing Oversight	High-risk action without approval	-15 points (max -45)
Data Policy Violation	Data handling violates declared policy	-25 points (max -50)
Unused Capability	Declared but not used (informational)	0 points

Compliance Score

Inkog calculates a 0-100 compliance score:

100: Perfect alignment between declared and detected behavior
75-99: Minor discrepancies (unused capabilities)
50-74: Moderate issues (some undeclared capabilities)
0-49: Major violations (missing oversight, data policy violations)

Full Example

Customer Support

INKOG.md


# Customer Support Agent
 
## Capabilities
- search_knowledge_base: Search internal documentation
- create_ticket: Create support tickets
- read_customer_data: View customer information
- send_response: Send templated responses
 
## Limitations
- Read-only access to customer data
- No access to payment information
- Maximum 5 tool calls per conversation
- No external API calls
 
## Human Oversight
- Require approval for: escalate_to_manager, issue_refund
- Notify on: negative sentiment, repeated issues
 
## Data Handling
- PII: redact before logging
- Credentials: never access
- Support history: retain 90 days

Financial Advisor

INKOG.md


# Financial Advisor Agent
 
## Capabilities
- portfolio_query (get_portfolio, view_holdings): Read portfolio data
- market_search: Search market information
- projection_calculator: Calculate investment projections
- report_generator: Generate PDF reports
 
## Limitations
- Read-only access to customer accounts
- No trade execution capability
- No access to external trading APIs
- Maximum 8000 tokens per session
 
## Human Oversight
- Require approval for: trade_recommendation, large_withdrawal
- Notify on: unusual market conditions, high-risk suggestions
 
## Data Handling
- Financial data: encrypt at rest
- Personal information: redact in reports
- Trading history: never log full details
- Account numbers: hash before storage

Code Assistant

INKOG.md


# Code Assistant Agent
 
## Capabilities
- read_file: Read source code files
- search_codebase: Search for patterns in code
- suggest_edit: Propose code changes
- run_tests: Execute test suites
 
## Limitations
- No write access to files
- No shell command execution
- No network access
- Sandbox-only code execution
 
## Human Oversight
- Require approval for: apply_changes, delete_code
- Notify on: large refactors, security-related changes
 
## Data Handling
- Source code: never send to external services
- API keys in code: redact before display
- Credentials: never log

High-Risk Actions

Inkog automatically flags these actions as requiring human oversight:

Category	Actions
Code Execution	`execute_code`, `run_code`, `exec`, `eval`
Communication	`send_email`, `send_message`
Destructive	`delete`, `remove`, `drop`
File Operations	`write_file`, `create_file`, `modify_file`
Permissions	`modify_permissions`, `change_permissions`
Financial	`payment`, `transfer`

If your agent uses any of these and they’re not in your Human Oversight section, Inkog generates a finding.

CLI Usage


# Scan with INKOG.md validation
inkog scan .
 
# Output compliance report as JSON
inkog scan . --format json
 
# Check specific governance issues
inkog scan . --pattern governance-*
 
# Generate compliance evidence
inkog scan . --format sarif > compliance-report.sarif

Compliance Mapping

INKOG.md findings map to regulatory frameworks:

INKOG.md Section	EU AI Act	NIST AI RMF	OWASP LLM
Capabilities (undeclared)	Article 15	MAP 1.3	LLM08 (Excessive Agency)
Human Oversight	Article 14	GOVERN 1.4	LLM08
Data Handling	Article 10	MEASURE 2.2	LLM06 (Sensitive Data)
Limitations (violated)	Article 15	MAP 3.1	LLM07 (Insecure Plugin)

Best Practices

Keep INKOG.md in project root - Inkog auto-detects it alongside AGENTS.md, README.md
Declare all tools - Even utility tools, to track capability sprawl
Use aliases for framework variations - search_web (web_search, google_search)
Update when code changes - Treat as living documentation
Run in CI/CD - Catch governance drift before deployment
Start with capabilities - Even a minimal INKOG.md improves visibility

INKOG.md vs AGENTS.md: These are different formats for different purposes.

AGENTS.md (Linux Foundation standard): Instructions for AI coding assistants (build commands, test commands, coding style)
INKOG.md: Governance declarations about your AI agent (capabilities, limitations, oversight)

You can have both files in your project - they serve different needs.

Human Oversight - EU AI Act Article 14 compliance
Audit Logging - Logging requirements
Compliance Reports - Generate evidence
Excessive Agency - LLM08 detection

INKOG.md Enhanced Governance Format

Quick Start

Create INKOG.md in your project root

Scan your project

Review compliance findings

Specification

Capabilities

Limitations

Human Oversight

Data Handling

Validation Engine

Finding Types

Compliance Score

Full Example

Customer Support

Financial Advisor

Code Assistant

High-Risk Actions

CLI Usage

Compliance Mapping

Best Practices

Related