Agent-Specific Mistakes

This is the short list of mistakes AI agents are most likely to make in the HiStruct ecosystem.

1. Wrong executable name

• Mistake: using HiStruct.Booster.exe
• Correct: FCS.HiStruct.Booster.exe
• Why it matters: automation fails before real debugging even begins.

2. Wrong space route key

• Mistake: assuming the route key matches the display name, for example skynet instead of sky
• Correct: verify the actual key through UserSession
• Why it matters: wrong keys often look like auth or API bugs.

3. Missing .fcsdrv / projection settings dependency

• Mistake: generating scenes without the required projection settings file
• Correct: ensure the relevant projection settings file is present and referenced
• Why it matters: scene generation can crash with little diagnostic help.

4. Forgetting UTF-16 for .fcscdm and .fcscdx

• Mistake: writing these files as UTF-8 by default
• Correct: save them as UTF-16
• Why it matters: the content may look fine, but the platform can still reject or misread it.

5. Not creating a new component instance after file changes

• Mistake: expecting an old instance to reflect updated component files automatically
• Correct: remember local component versions are pinned by creation-time timestamps
• Why it matters: agents can think their fix failed when they are testing the wrong version.

6. Blaming auth code for a 403

• Mistake: debugging tokens, headers, or request code first
• Correct: check role assignment and UserSession first
• Why it matters: many 403s are permission issues, not code issues.

7. Trying interactive fli in a non-TTY shell

• Mistake: launching console-interactive fli in a shell that does not provide a real TTY
• Correct: use async interaction or --i-json
• Why it matters: the tool may hang or behave unpredictably.

8. Using relative paths with --fcs

• Mistake: passing a relative .fcs path to --fcs
• Correct: always pass an absolute path
• Why it matters: relative paths can trigger the path-doubling bug.

Fast pre-flight check for agents

Before debugging deeper, verify:

• executable name
• absolute paths
• route key from UserSession
• file encoding for .fcscdm / .fcscdx
• required projection settings files
• account roles
• whether you are testing a fresh component instance