Smithery is now a part of Arcade.dev! Read more in our announcement here
Expert record keeping system with paperless-ngx integration, country-specific taxonomies, and intelligent document management...
Expert record keeping with paperless-ngx integration, country-specific taxonomies, and safe deletion practices
The Records Manager Skill is a subject matter expert in record keeping and document management. It integrates with paperless-ngx to provide intelligent document organization, trust-specific expertise, automated workflow management, and safe deletion practices.
Core Capabilities:
Key Safety Feature: Document deletion ALWAYS requires explicit approval through the DeleteConfirmation workflow. This prevents catastrophic data loss.
When executing workflows, send voice notification:
curl -s -X POST http://localhost:8888/notify \
-H "Content-Type: application/json" \
-d '{"message": "Running the WORKFLOWNAME workflow from the Records Manager skill"}' \
> /dev/null 2>&1 &
| Trigger | Workflow | Purpose |
|---|---|---|
| Upload intent | Workflows/UploadWorkflow.md |
Add documents with intelligent tagging |
| Search intent | Workflows/SearchWorkflow.md |
Find documents by tags, content, type |
| Organize intent | Workflows/OrganizeWorkflow.md |
Suggest and apply taxonomy improvements |
| Tag intent | Workflows/TagWorkflow.md |
Add or modify tags on documents |
| Delete intent | Workflows/DeleteConfirmation.md |
MANDATORY approval workflow |
| Retention intent | Workflows/RetentionWorkflow.md |
Check retention requirements |
| Info intent | Workflows/InfoWorkflow.md |
Get document details and metadata |
| "Navigate taxonomy" | Use TaxonomyExpert hierarchical methods | Browse Function→Service→Activity→DocumentType |
| "Add new entity" | Workflows/AddEntityWorkflow.md |
Create new entity interactively |
| "Create a workflow" | Workflows/WorkflowCreator.md |
Analyze documents and recommend workflow |
| "Review workflow" | Workflows/WorkflowReview.md |
Analyze workflow effectiveness |
| "Trust documents" | Workflows/TrustValidation.md |
Validate trust document completeness |
| "FTE retention" | Workflows/FTECheck.md |
Check Family Trust Election retention |
| "Update taxonomies" | Workflows/TaxonomyUpdate.md |
Sync taxonomy changes from YAML to paperless-ngx |
| "Check status" | Workflows/StatusCheck.md |
Test connection and verify system status |
Example 1: Upload a tax document
User: "Store this medical receipt for tax"
→ Invokes Upload workflow
→ TaxonomyExpert suggests tags: medical, receipt, tax-deductible, 2024
→ Uploads to paperless-ngx with metadata
→ Returns: "Document uploaded as #1234 with tags: medical, receipt, tax-deductible"
Example 2: Check retention before deletion
User: "Can I delete my 2019 tax returns?"
→ Invokes Retention workflow
→ Checks ATO requirements: 5 years from lodgment
→ Returns: "⚠️ Retain until 2025-06-30. 2019 returns filed in 2020 must be kept 5 years."
Example 3: Validate trust compliance
User: "Validate Smith Family Trust documents"
→ Invokes TrustValidation workflow
→ Checks required documents against trust type checklist
→ Returns: "8/10 documents found. Missing: Beneficiary Declaration, 2024 Distribution Minutes"
Triggers:
Process:
CLI Command:
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts upload <file> --domain <domain>
Triggers:
Process:
CLI Command:
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts search --query <text> --tags <tags> --type <type>
Triggers:
Process:
CLI Command:
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts organize --domain <domain> --apply
Triggers:
Process:
CLI Command:
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts tag <docIds> <tagNames>
Triggers:
Process:
MANDATORY APPROVAL PHRASE:
I understand this cannot be undone and I want to proceed with deleting N documents
Do NOT accept:
CLI Command:
# This command REFUSES to delete and points to the workflow
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts delete <query>
Why This Matters: Deleting records is catastrophic. Tax documents, legal papers, insurance policies - once deleted, they're gone forever. The confirmation workflow ensures:
Triggers:
Process:
CLI Command:
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts retention --domain <domain>
Triggers:
Process:
CLI Command:
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts info <docId>
Triggers:
Process:
Example:
User: "Add a family trust for Smith family"
AI: "Creating Smith Family Trust entity..."
"I'll need some information:"
" - Trustee name?"
" - ABN?"
" - Family Trust Election date?"
" - TFN (optional)?"
[Creates entity tag, storage path, custom fields]
"✅ Entity created: smith-family-trust-2024"
" Documents can now be tagged with 'entity:smith-family-trust'"
Triggers:
Process:
Example:
User: "Recommend a workflow for Smith Family Trust documents"
AI: "Analyzing 47 documents tagged 'smith-family-trust'..."
"Recommendation (high confidence):"
" Match: 'Smith.*Trust|Family.*Trust.*Smith'"
" Assign tag: entity:smith-family-trust"
" Assign storage path: /Trusts/Family/Smith Family Trust"
" Assign document type: Auto-detect from content"
" Reasoning: 45/47 documents match this pattern"
"Approve? (yes/no)"
Triggers:
Process:
Triggers:
Process:
Example:
User: "Validate Smith Family Trust documents"
AI: "Checking Smith Family Trust completeness..."
"Required documents (10):"
" ✅ Trust Deed"
" ✅ Family Trust Election (FTE) - Retain until 2025-02-01"
" ✅ Trustee Appointment"
" ⚠️ Beneficiary Declaration - MISSING"
" ✅ ABN Registration"
" ❌ TFN Registration - NOT FOUND"
" ✅ Annual Financial Statements (2023)"
" ⚠️ Trustee Resolution (2024) - NOT YET CREATED"
" ⚠️ Distribution Minutes (2024) - NOT YET CREATED"
" ✅ Tax Return (2023)"
""
"Action items:"
" 1. Upload Beneficiary Declaration"
" 2. Upload TFN Registration"
" 3. Create pre-EOFY trustee resolution (before June 30)"
" 4. Document beneficiary distributions for 2024"
Triggers:
Process:
Example:
User: "When can I delete my Family Trust Election document?"
AI: "Family Trust Election Date: 2020-02-01"
"Retention Period: 5 years from FTE date"
"Retain Until: 2025-02-01"
""
"⚠️ DO NOT DELETE before 2025-02-01"
"ATO Requirement: Section 272-80 ITAA 1936"
"Reason: FTE must be retained for 5 years from lodgment date"
""
"Current Date: 2025-01-17"
"Days Remaining: 15 days"
""
"After 2025-02-01, you may safely delete this document"
Triggers:
Process:
CLI Commands (MANDATORY - DO NOT bypass):
# Check for available updates (safe, read-only)
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts check-updates --country Australia
# Apply updates WITHOUT retention changes (safe)
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts sync-taxonomies --country Australia
# Apply updates WITH retention changes (requires approval)
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts sync-taxonomies --country Australia --approve-retention-changes
# View taxonomy version history
bun run $PAI_DIR/skills/RecordsManager/Tools/RecordManager.ts diff-taxonomies
Example:
User: "Sync taxonomies for Australia"
AI: "Checking for taxonomy updates..."
"Changes detected:"
" NEW TAGS:"
" • trust-documents (category: legal)"
" • beneficiary-declaration (category: trust)"
" NEW DOCUMENT TYPES:"
" • Family Trust Election"
" • Distribution Minutes"
" RETENTION CHANGES:"
" ⚠️ Tax Return: 5 years → 7 years (requires approval)"
""
"Apply non-retention changes? (yes/no)"
[User: yes]
"✅ Applied 2 new tags, 2 new document types"
""
"⚠️ Retention change requires explicit approval:"
" Tax Return: 5 years → 7 years"
" Reason: ATO requirement update (Section 262A ITAA 1936)"
" Impact: Affects 47 documents currently tagged 'tax-return'"
""
"Type 'APPROVE' to apply retention changes:"
[User: APPROVE]
"✅ Applied retention changes"
"📝 Logged to $PAI_HOME/MEMORY/RECORDSMANAGER/taxonomy-updates.jsonl"
CRITICAL SAFEGUARDS:
src/skills/RecordsManager/Config/taxonomies.yamlWhy This Matters: Taxonomy changes affect compliance. Incorrect retention periods, invented tags, or bypassing the CLI can cause:
The TaxonomyExpert provides country-specific record keeping knowledge:
Australia (default)
United States
United Kingdom
Household:
Corporate:
Trusts:
Unit Trusts (NEW)
Discretionary Trusts (NEW)
Family Trusts (NEW)
Projects:
The Records Manager now supports hierarchical taxonomies with a 4-level structure for precise document classification:
Level 1: Function → Level 2: Service → Level 3: Activity → Level 4: DocumentType
HealthManagement/
├── MedicalCare/
│ ├── Consultations/
│ │ ├── Medical Receipt
│ │ ├── Referral Letter
│ │ └── Specialist Referral
│ ├── Prescriptions/
│ │ ├── Prescription
│ │ └── Medication Receipt
│ └── TestResults/
│ ├── Pathology Report
│ └── Imaging Report
└── DentalCare/
└── Consultations/
├── Dental Invoice
└── Treatment Plan
Navigation Methods (Function → Service → Activity → DocumentType):
// Get all functions for an entity type
const functions = expert.getFunctions('household');
// Returns: [{ name: 'HealthManagement', keywords: [...], services: {...} }, ...]
// Get services for a function
const services = expert.getServices('household', 'HealthManagement');
// Returns: [{ name: 'MedicalCare', keywords: [...], activities: {...} }, ...]
// Get activities for a service
const activities = expert.getActivities('household', 'HealthManagement', 'MedicalCare');
// Returns: [{ name: 'Consultations', documentTypes: [...], retention: {...} }, ...]
// Get document types for an activity
const docTypes = expert.getDocumentTypesForActivity(
'household',
'HealthManagement',
'MedicalCare',
'Consultations'
);
// Returns: ['Medical Receipt', 'Referral Letter', 'Specialist Referral']
// Get retention rules for an activity
const retention = expert.getRetentionForActivity(
'household',
'HealthManagement',
'MedicalCare',
'Consultations'
);
// Returns: { AUS: { years: 7, authority: 'ATO requirement...' }, USA: { years: 6, ... } }
Path Validation and Autocomplete:
// Validate a complete taxonomy path
const validation = expert.validatePath('household', 'HealthManagement/MedicalCare/Consultations');
// Returns: { valid: true, resolved: { function: 'HealthManagement', service: 'MedicalCare', activity: 'Consultations', documentTypes: [...], retention: {...} } }
// Autocomplete with fuzzy matching
const autocomplete = expert.autocomplete('household', 'health/med', { limit: 5 });
// Returns: { suggestions: ['HealthManagement/MedicalCare'], types: ['service'], remaining: 2 }
// Search by keyword
const results = expert.searchByKeyword('household', 'medical');
// Returns: [{ function: 'HealthManagement', service: 'MedicalCare', activity: 'Consultations', matchType: 'keyword', relevance: 7 }, ...]
Tag and Path Generation:
// Generate hierarchical tags for paperless-ngx
const tags = expert.generateHierarchicalTags(
'household',
'HealthManagement',
'MedicalCare',
'Consultations'
);
// Returns: ['HealthManagement', 'MedicalCare', 'Consultations', 'medical', 'doctor', 'clinic']
// Generate storage path
const path = expert.generateStoragePath(
'household',
'HealthManagement',
'MedicalCare',
'Consultations'
);
// Returns: '/Household/Health Management/Medical Care/Consultations'
Helper Methods:
// Get all document types across entire hierarchy (flat view)
const allDocTypes = expert.getAllDocumentTypes('household');
// Returns: ['Medical Receipt', 'Referral Letter', 'Tax Return', 'Invoice', ...]
// Check if hierarchical mode is available
if (expert.isHierarchicalAvailable()) {
// Use hierarchical methods
} else {
// Fall back to flat taxonomy
}
// Get current taxonomy mode
const mode = expert.getTaxonomyMode();
// Returns: 'hierarchical' | 'flat' | 'hybrid'
Upload Workflow with Hierarchical Classification:
// User uploads a medical receipt
const expert = new TaxonomyExpert('AUS', 'household');
// Option 1: Let expert suggest from filename/content
const suggestion = expert.suggestMetadata('Medical-Receipt-DrSmith-2024.pdf');
// Option 2: Navigate hierarchy interactively
const functions = expert.getFunctions('household');
// User selects: HealthManagement
const services = expert.getServices('household', 'HealthManagement');
// User selects: MedicalCare
const activities = expert.getActivities('household', 'HealthManagement', 'MedicalCare');
// User selects: Consultations
const docTypes = expert.getDocumentTypesForActivity('household', 'HealthManagement', 'MedicalCare', 'Consultations');
// User selects: Medical Receipt
// Generate tags and path
const tags = expert.generateHierarchicalTags('household', 'HealthManagement', 'MedicalCare', 'Consultations');
const storagePath = expert.generateStoragePath('household', 'HealthManagement', 'MedicalCare', 'Consultations');
// Upload to paperless-ngx with hierarchical metadata
await client.uploadDocument(filePath, {
tags: tags,
document_type: 'Medical Receipt',
storage_path: storagePath,
});
Retention Checking with Hierarchical Rules:
// Check retention for specific activity
const retention = expert.getRetentionForActivity(
'household',
'HealthManagement',
'MedicalCare',
'Consultations'
);
console.log(`Keep for ${retention.AUS.years} years`);
console.log(`Legal basis: ${retention.AUS.authority}`);
Required environment variables (set in $PAI_DIR/.env):
# Paperless-ngx connection
MADEINOZ_RECORDMANAGER_PAPERLESS_URL="https://paperless.example.com"
MADEINOZ_RECORDMANAGER_PAPERLESS_API_TOKEN="your-api-token-here"
# Records Manager settings
MADEINOZ_RECORDMANAGER_RECORDS_COUNTRY="Australia" # Your country for compliance
MADEINOZ_RECORDMANAGER_RECORDS_DEFAULT_DOMAIN="household" # household | corporate | projects
Trust Document Management:
Workflow Automation:
Dynamic Entity Creation:
Household Record Keeping:
Corporate Compliance:
Project Management:
Trust Management (NEW):
Problem: "Country not supported, falling back to Australia"
Solution: Taxonomies available for Australia, United States, United Kingdom. For other countries, contribute your country's guidelines!
Problem: "Cannot reach paperless-ngx API"
Solution: Verify MADEINOZ_RECORDMANAGER_PAPERLESS_URL includes protocol (https://) and instance is running
Problem: "API authentication failed"
Solution: Regenerate API token in paperless-ngx with correct permissions
Problem: "No tags suggested"
Solution: Document type or filename may not match known patterns. Manually tag first few to build patterns.
status CLI command for comprehensive connection testing