[WIP] Fix documentation to match code implementation

[Copilot]

Documentation Fixes for API Mismatches

Completed Changes

• README.md - Fix Quick Start section (lines 34-76)

  • Updated enroll_device() signature and return value
  • Updated verify_device() signature and return value
  • Removed non-existent PolicyEngine.evaluate() and ConsequenceHandler.execute()
  • Updated with correct consequence management pattern

• README.md - Fix API Reference section (lines 446-501)

  • Updated OfflineVerifier constructor signature (config parameter, not storage_path)
  • Updated enroll_device() signature (device_name, pcr_indices, validity_seconds)
  • Updated verify_device() signature (fingerprint_id, policy_id)
  • Removed non-existent methods: revoke_device(), list_devices()
  • Fixed PolicyEngine API (create_policy, validate_fingerprint, get_policy, list_policies)
  • Fixed ConsequenceHandler API (register_credential, revoke_credential, register_vault, lock_vault, register_token, invalidate_token)

• README.md - Fix CLI Usage section (lines 566-583)

  • Updated all CLI commands to use trustcore-tpm (actual entry point)
  • Fixed command syntax to match actual CLI implementation
  • Removed non-existent commands (list, revoke, tpm-info)
  • Added correct commands (list-fingerprints, list-policies, status, challenge, compare, audit)

• QUICKSTART.md - Fix Quick Start section (lines 20-50)

  • Updated CLI commands from tpm-fingerprint to trustcore-tpm
  • Updated Python example with correct API (device_name parameter, proper error handling)
  • Added validity_seconds parameter to enrollment

• USAGE_GUIDE.md - Fix CLI section (lines 419-470)

  • Changed all CLI commands from tpm-fingerprint to trustcore-tpm
  • Verified CLI command syntax matches implementation

• USAGE_GUIDE.md - Verified Basic Operations section (lines 192-244)

  • Confirmed already shows correct implementation

• RELEASE_NOTES.md - Fix Quick Start example

  • Updated example code with correct API

Summary of Changes

All documentation now correctly reflects the actual implementation:

• enroll_device(device_name, pcr_indices, validity_seconds) returns dict with fingerprint_id, policy_id, device_name, enrolled_at
• verify_device(fingerprint_id, policy_id) returns bool or raises exceptions
• CLI command is trustcore-tpm (not tpm-fingerprint)
• Consequences are automatic via OfflineVerifier.consequence_handler
• Resources registered with register_credential(), register_vault(), register_token()
• PolicyEngine uses create_policy() and validate_fingerprint() (not evaluate())
• ConsequenceHandler uses register/revoke/lock methods (not execute())

Original prompt

Overview

The documentation (README.md, QUICKSTART.md, USAGE_GUIDE.md) contains significant mismatches with the actual code implementation. This causes confusion for users trying to follow examples.

Critical Mismatches

1. enroll_device() Parameter and Return Values

• Docs claim: enroll_device(device_id) returns result["success"]
• Code implements: enroll_device(device_name, pcr_indices, validity_seconds) returns dict with fingerprint_id, policy_id, device_name, enrolled_at (no "success" key)

2. verify_device() Signature

• Docs claim: verify_device(device_id) returns verification['valid']
• Code implements: verify_device(fingerprint_id, policy_id) returns boolean or raises exceptions

3. CLI Command Names

• Docs show: trustcore-tpm enroll --device-id device-001
• Code implements: tpm-fingerprint enroll MyDevice -o enrollment.json

4. PolicyEngine API

• Docs claim: PolicyEngine.evaluate(device_id, policy) and register_policy()
• Code implements: create_policy(name, pcr_baseline) and validate_fingerprint(fingerprint, policy)

5. ConsequenceHandler API

• Docs claim: execute(device_id, violations) and register_consequence()
• Code implements: register_credential(), revoke_credential(), register_vault(), lock_vault(), etc.

6. Missing Methods in Documentation

• Docs claim: revoke_device(), list_devices() methods exist
• Code: These methods are NOT implemented

7. OfflineVerifier Constructor

• Docs claim: __init__(storage_path: str = "~/.tpm_fingerprint/")
• Code implements: __init__(config: Optional[Config] = None)

Files to Update

1. README.md - Fix:

   • Quick Start examples (lines 34-76)
   • API Reference sections (lines 446-501)
   • CLI Usage (lines 566-583)

2. QUICKSTART.md - Fix:

   • Quick start examples (lines 20-50)
   • CLI commands (lines 23-50)

3. USAGE_GUIDE.md - Fix:

   • Basic operations (lines 192-244)
   • Command-line interface (lines 419-470)

Correct Implementation Details

The actual working implementation should show:

• enroll_device(device_name, validity_seconds=None, pcr_indices=None) → returns dict with fingerprint_id, policy_id, device_name, enrolled_at
• verify_device(fingerprint_id, policy_id) → returns bool or raises exceptions
• CLI command: tpm-fingerprint (not trustcore-tpm)
• Consequences are automatic via OfflineVerifier.consequence_handler
• Resources registered with register_credential(), register_vault(), register_token()

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.