Add AI agent guide for translating C/C++ structs and datasheets to Emboss

[Copilot]

AI agents (Copilot, Gemini, Claude, etc.) need structured guidance to translate C/C++ packed structs with bitfields and electronic datasheet tables into idiomatic Emboss definitions.

Changes

• doc/ai-agent-guide.md - 867-line comprehensive translation guide covering:

  • Quick translation rules for C/C++ __attribute__((packed)) structs and bitfields
  • Complete feature reference (structs, bits, enums, arrays, conditionals, virtual fields, parameters)
  • 5 detailed examples including a comprehensive example demonstrating ALL major Emboss features in one struct
  • Common patterns: length-prefixed messages, tagged unions, header+payload+footer, bit-packed flags
  • Decision tree, quick reference card, troubleshooting section

• README.md and doc/index.md - Added references to guide for discoverability

Example 1: Comprehensive Feature Demonstration

Example 1 has been updated to demonstrate 14 major Emboss features in a single realistic sensor telemetry packet:

Features Demonstrated:

• ✅ Virtual Fields (let) - 6 examples including computed enums, aliases, and field existence checks
• ✅ Conditional Fields (if) - extended_cal and checksum fields based on conditions
• ✅ Anonymous bits - inline bitfield for flags byte
• ✅ Enums - SensorType and DataQuality with multiple values
• ✅ Arrays - variable-length UInt:16[n] samples
• ✅ Flags - enabled, calibrated, low_battery, checksum_present
• ✅ Requires statements - struct-level and field-level validation with range checks
• ✅ $next keyword - automatic offset calculation throughout the struct
• ✅ Nested struct (subtype) - CalibrationData defined within SensorTelemetry
• ✅ $size_in_bytes - dynamic field sizing based on nested struct
• ✅ Aliases - cal_offset as alias to calibration_offset
• ✅ $present() function - check if conditional fields exist
• ✅ Signed integers (Int) - calibration_offset with range validation
• ✅ text_output attribute - control field visibility in text output

Input (C):

#pragma pack(push, 1)
struct SensorTelemetry {
    uint8_t version;
    uint8_t sensor_id;
    uint8_t flags;          // Bitfield
    uint8_t sample_count;
    uint16_t samples[8];    // Variable array
    int16_t calibration;    // Signed calibration offset
    uint32_t timestamp;
    uint16_t checksum;      // Optional
};
#pragma pack(pop)

Output (Emboss) - includes virtual fields, conditional fields, anonymous bits, enums, arrays, flags, requires statements, $next keyword, nested structs, $size_in_bytes, aliases, $present(), signed Int, and text_output attribute all in one comprehensive example.

Example 2: Datasheet Table Translation

Input (datasheet table):

Offset | Size | Field Name | Description
0x00   | 1    | SYNC       | Sync byte (0xAA)
0x01   | 1    | CMD        | Command code
0x02   | 2    | LENGTH     | Payload length

Output (Emboss):

[$default byte_order: "BigEndian"]
[(cpp) namespace: "device::protocol"]

struct Message:
  0 [+1]  UInt  sync
    [requires: this == 0xAA]
  1 [+1]  UInt  command
  2 [+2]  UInt  length (n)
  4 [+n]  UInt:8[]  payload

Example 3: C Bitfield Translation

Input (C bitfield):

struct __attribute__((packed)) ControlReg {
    uint32_t enable : 1;
    uint32_t mode : 2;
    uint32_t threshold : 8;
};

Output (Emboss):

bits ControlReg:
  0  [+1]  Flag  enable
  1  [+2]  UInt  mode
  3  [+8]  UInt  threshold

All examples have been validated by compiling with embossc to ensure correct syntax.

Original prompt

create a markdown file that can be used by AI agents such as co-pilot or Gemini etc providing them instructions on how to translate user prompts into beautiful expertly crafted emboss structs, using the full feature set as needed. The typical use cases would be that a user supplies a c or C++ packed struct that could include bitfields, or perhaps the user copies and pastes a table from a electronics data sheet

---

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

[AaronWebster]

@copilot The example struct is too simple. Create one struct that has ALL of the following:

Virtual Fields
Conditional Fields
Anonymous bits
Enums
Arrays
Flags
Requires statements

Thoroughly review the emboss language features guide for any that I've made

[AaronWebster]

@copilot The example struct is too simple. Create one struct that has ALL of the following:

Virtual Fields
Conditional Fields
Anonymous bits
Enums
Arrays
Flags
Requires statements

Thoroughly review the emboss language features guide for any that are not be enumerated above

[Copilot]

@copilot The example struct is too simple. Create one struct that has ALL of the following:

Virtual Fields ...

Updated Example 1 to demonstrate ALL requested features in a single comprehensive struct:

✅ Virtual Fields - 5 examples (sensor_type, data_quality, is_reliable, timestamp_offset, has_samples)
✅ Conditional Fields - checksum field only present when checksum_present flag is set
✅ Anonymous bits - flags byte broken into Flag and UInt bitfields
✅ Enums - SensorType and DataQuality with multiple values
✅ Arrays - variable-length UInt:16[n] samples array
✅ Flags - enabled, calibrated, low_battery, checksum_present
✅ Requires statements - both struct-level (combined validation) and field-level constraints

The example has been validated by compiling with embossc to ensure correct syntax.

Commit: 932ac37

[Copilot]

@copilot The example struct is too simple. Create one struct that has ALL of the following:

Virtual Fields ...

Enhanced Example 1 with additional features from the language reference that weren't in the original list:

Now includes 14 major features:
✅ Virtual Fields (6 examples)
✅ Conditional Fields (2 examples)
✅ Anonymous bits
✅ Enums (2 types)
✅ Arrays (variable-length)
✅ Flags (4 flags)
✅ Requires statements (struct + field level)
✅ $next keyword - automatic offset calculation
✅ Nested struct - CalibrationData subtype
✅ $size_in_bytes - dynamic field sizing
✅ Aliases - cal_offset
✅ $present() - check field existence
✅ Signed Int - calibration values
✅ text_output attribute - visibility control

Validated by compiling with embossc to ensure correct syntax.

Commit: b31214e