# Untitled — HC v1.1
> Source: https://ideas.asapai.net/hypercontext-hc-standard
> Type: framework | ID: hc-framework-standard-v1.1

---
## hc-metadata
{
  "hc_version": "1.1",
  "hc_type": "framework",
  "artifact_id": "hc-framework-standard-v1.1",
  "artifact_name": "HyperContext Standard v1.1 Specification",
  "version": "1.1.0",
  "created": "2026-02-08T10:00:00Z",
  "updated": "2026-02-08T10:00:00Z",
  "content_hash": "sha256:placeholder-for-actual-hash",
  "metadata_hash": "sha256:placeholder-for-actual-hash",
  "classification": {
    "category": "specification",
    "subcategory": "standard-definition",
    "tags": [
      "hypercontext",
      "hc-standard",
      "specification",
      "rci",
      "neural-registry",
      "framework"
    ]
  },
  "provenance": {
    "generated_by": "human-authored",
    "authors": [
      "MasteryMade"
    ],
    "organization": "MasteryMade",
    "license": "MIT"
  },
  "content_metadata": {
    "word_count": 15000,
    "estimated_read_time": "45 minutes",
    "complexity": "expert",
    "audience": [
      "developers",
      "ai-engineers",
      "prompt-engineers",
      "product-builders"
    ]
  },
  "relationships": {
    "parent_artifacts": [],
    "related_artifacts": [
      "hc-skill-template-v1",
      "hc-registry-template-v1",
      "hc-identity-template-v1"
    ],
    "child_artifacts": [],
    "implements": [],
    "supersedes": [
      "hc-framework-standard-v1.0"
    ]
  },
  "access": {
    "public": true,
    "shareable": true,
    "downloadable": true,
    "license": "MIT"
  },
  "summary": "Complete HC Standard v1.1 specification defining the open standard for portable AI context. Includes Three Laws, file structure requirements, metadata schemas, Neural Registry protocol, RCI mechanism, self-executing agent architecture, and integrity validation. Enables compound learning across LLM interactions through Recursive Context Injection."
}

---
## hc-instructions
# HyperContext Standard v1.1 Specification
# This document IS the standard it describes

## For LLMs: How to Use This Document

When implementing HC v1.1 compliance:

1. **Read Complete Spec**: This document defines all requirements
2. **Follow Structure**: Use templates and patterns exactly as specified
3. **Validate Compliance**: Check all requirements before claiming HC v1.1
4. **Reference Sections**: Link to specific sections when explaining features

## What This Document Contains

- **Three Laws**: Core principles (Container, Hidden Brain, Linkage)
- **File Structure**: Required HTML structure and metadata blocks
- **Canonical Types**: 5 standard types (registry, skill, artifact, identity, framework)
- **Neural Registry Protocol**: How registries work, discovery, lazy loading
- **Self-Executing Agents**: NEW in v1.1 - embedded agent architecture
- **Integrity System**: NEW in v1.1 - content/metadata hashing
- **Token Economics**: Optimization strategies
- **Complete Templates**: Production-ready examples

## What's New in v1.1

### Major Changes:
1. **Split Metadata Blocks**:
   - Schema.org JSON-LD for SEO/public
   - hc-metadata JSON for agent contract (NEW)
   - Cleaner separation of concerns

2. **Canonical 5 Types**:
   - registry (Neural Registry routers)
   - skill (Transformation tools)
   - artifact (Generated outputs)
   - identity (Voice/style context)
   - framework (Methodologies/specifications)

3. **Dual Registry Format**:
   - HTML for humans + agents
   - /registry.json for agents only (98% token savings)

4. **Self-Executing Architecture**:
   - mastery-agent-config block (execution parameters)
   - mastery-agent-knowledge block (skill knowledge)
   - Skills become applications, not instructions

5. **Integrity Validation**:
   - content_hash (SHA-256 of human content)
   - metadata_hash (SHA-256 of hc-metadata)
   - Enables caching, change detection, versioning

### Backward Compatibility:
- HC v1.0 files still work
- New agents handle both versions
- Migration path documented

## Implementation Checklist

When creating HC v1.1 compliant files:

### Required Blocks:
□ Schema.org JSON-LD (SEO)
□ hc-metadata JSON (agent contract) - NEW in v1.1
□ hc-instructions (LLM instructions)
□ hc-human-docs (visible documentation)

### Optional Blocks:
□ hc-frontmatter (human-readable YAML)
□ hc-python (Python helpers)
□ mastery-agent-config (for self-executing skills) - NEW in v1.1
□ mastery-agent-knowledge (for self-executing skills) - NEW in v1.1

### Validation:
□ Valid HTML5 structure
□ All required metadata fields present
□ Unique artifact_id
□ ISO 8601 timestamps
□ Content/metadata hashes calculated - NEW in v1.1
□ Canonical type specified - NEW in v1.1
□ Summary within 50-100 tokens
□ Proper version number (semver)

### Quality:
□ Renders correctly in browser
□ LLM can parse instructions
□ Launch links work (if skill)
□ Professional appearance
□ Complete documentation

## Common Implementation Patterns

### Pattern 1: Basic Skill
- Schema.org + hc-metadata + hc-instructions + hc-human-docs
- No self-execution, manual launch links
- Standard Neural Registry integration (Step 0)

### Pattern 2: Self-Executing Skill (NEW in v1.1)
- All of Pattern 1 PLUS:
- mastery-agent-config (defines execution parameters)
- mastery-agent-knowledge (skill-specific knowledge)
- Embedded agent activates on page load
- Zero-friction user experience

### Pattern 3: Neural Registry
- Dual format: HTML + /registry.json
- Complete artifact catalog
- LLM protocol instructions embedded
- Human-readable dashboard interface

### Pattern 4: Identity Context
- Defines user voice, style, frameworks
- Referenced by skills for personalization
- Applied throughout session
- Enables RCI consistency

### Pattern 5: Framework/Specification
- Comprehensive documentation
- Examples and templates
- Self-referential (like this document)
- Educational content

## Token Optimization Strategy

When implementing Neural Registry loading:

1. **Registry Scan** (~100 tokens):
   - Fetch /registry.json OR parse HTML
   - Extract artifact metadata only
   - Calculate relevance scores
   - Present top matches to user

2. **Identity Load** (~500 tokens):
   - Fetch identity_url if present
   - Parse voice/style/frameworks
   - Apply to session
   - Cache for duration

3. **Lazy Artifact Loading**:
   - Step A: Fetch artifact URL
   - Step B: Parse YAML frontmatter only (~200 tokens)
   - Step C: Validate relevance from metadata
   - Step D: IF still relevant, fetch content (~2000-5000 tokens)
   - Step E: Apply context to current task

4. **Limits**:
   - Recommend max 3 artifacts per execution
   - Total budget: ~10,200 tokens with 3 artifacts
   - vs loading all 50 artifacts: ~250,000 tokens
   - Savings: 96%

## Error Handling

Gracefully handle:
- Registry fetch failures → Ask for corrected URL
- Artifact fetch failures → Continue with available
- Identity fetch failures → Use defaults
- Python execution unavailable → Fall back to manual
- Code sandbox unavailable → Explain requirements
- Invalid JSON/YAML → Report specific error
- Missing required fields → Request completion

## Anti-Patterns (Avoid)

❌ Mixing SEO and agent metadata in single block
❌ Creating custom types beyond canonical 5
❌ Hardcoding platform-specific logic
❌ Auto-loading artifacts without user permission
❌ Exceeding token budgets (>3 artifacts)
❌ Skipping quality validation
❌ Missing integrity hashes in v1.1 files
❌ Non-unique artifact_ids
❌ Summaries >100 tokens
❌ Breaking backward compatibility unnecessarily

## Best Practices

✅ Use canonical types consistently
✅ Calculate actual hashes (don't use placeholders in production)
✅ Implement dual registry format (/registry.json)
✅ Add self-execution for premium skills
✅ Respect token budgets
✅ Enable lazy loading
✅ Maintain backward compatibility
✅ Provide clear documentation
✅ Include complete examples
✅ Test across LLM platforms
✅ Validate with real users

## Migration from v1.0 to v1.1

### Step-by-Step:
1. Add hc-metadata block (new agent contract)
2. Calculate content_hash and metadata_hash
3. Update hc_type to canonical 5
4. Add version field (semver)
5. Optional: Add self-execution blocks
6. Optional: Create /registry.json endpoint
7. Keep existing v1.0 blocks (backward compat)
8. Test with both old and new agents

### What to Change:
- hc_version: "1.0" → "1.1"
- Add hc-metadata script block
- Add integrity hashes
- Standardize types to canonical 5
- Add version field with semver

### What to Keep:
- All v1.0 blocks (backward compatible)
- Existing URLs and references
- Current file structure
- LLM instructions
- Human documentation

## Version Strategy

**For Files:**
- Use semver: 1.0.0, 1.1.0, 2.0.0
- Increment major for breaking changes
- Increment minor for new features
- Increment patch for fixes

**For Standard:**
- v1.0: Initial release
- v1.1: Additive improvements (this version)
- v2.0: (Future) If breaking changes needed

## Support Resources

- **Specification**: This document
- **Templates**: See Section 9
- **Examples**: Throughout document
- **Repository**: https://github.com/masterymade/hypercontext
- **Community**: https://skills.masterymade.com
- **Issues**: https://github.com/masterymade/hypercontext/issues

## Quick Reference

**Canonical Types**: registry | skill | artifact | identity | framework

**Required Blocks**: Schema.org + hc-metadata + hc-instructions + hc-human-docs

**New in v1.1**: hc-metadata, integrity hashes, self-execution, /registry.json

**Token Budget**: Registry ~100, Identity ~500, Artifacts 3x~3k each

**Three Laws**: Container (HTML5) + Hidden Brain (embedded instructions) + Linkage (referenceable)