tushell

Capability Narrative CLI Context-Aware Story Ops Terminal

This document provides a comprehensive roadmap and documentation for the Capability Narrative CLI Context-Aware Story Ops Terminal in the tushell project. It serves as a full scaffolding for other agents to understand the purpose, features, and implementation details of this capability.

Overview

The Capability Narrative CLI Context-Aware Story Ops Terminal is designed to enhance the narrative experience for users by providing context-aware commands and real-time updates on character states within the narrative. It integrates various components such as GraphBuilderSync, EchoNode, and RedStoneWriter to achieve this goal.

Key Features

• Context-aware commands: Commands like mia status and tushell echo respond based on the current narrative context, providing relevant information about the state or status of characters.
• GraphBuilderSync integration: Synchronizes data or processes across nodes with options for api-url, token, node-id, node-data, action, and narrative.
• EchoNode synchronization: Fetches and processes data related to character states using the EchoNode API, providing real-time updates on character states.
• RedStoneWriter features: Commands like redstone-encode-resonance, redstone-write-narrative-diffs, and redstone-sync-echonode-metadata enhance the narrative experience by integrating narrative elements into the development process.
• Memory key graph visualization: The draw-memory-graph command prints an ASCII-rendered graph of the memory keys and Arc structure, incorporating data from EchoNode::LatticeDrop.

Integration with GraphBuilderSync

To integrate GraphBuilderSync with the CLI, follow these steps:

• Add a new command to the CLI for GraphBuilderSync operations. This command should accept options for api-url, token, node-id, node-data, action, and narrative.
• Implement the logic for the graphbuilder_sync_command in the CLI to handle the push and pull actions using the GraphBuilderSync class.
• Ensure the command provides appropriate feedback to the user, including success or error messages.

For more details, refer to the implementation in tushell/tushell/tushellcli.py and the GraphBuilderSync class in tushell/tushell/echonexus/graphbuildersync.py.

Character-state Queries

The purpose of character-state queries in the tushell CLI is to provide information about the current state or status of characters within the narrative context. These queries allow users to interact with and retrieve data about characters, enhancing the narrative experience.

• character-state queries support commands like mia status and tushell echo, which provide information about the status or state of characters.
• These queries are designed to be context-aware, meaning they respond based on the current narrative context.
• They help users understand the current state of characters and their roles within the ongoing narrative.
• The implementation of these queries can be found in the CLI commands and the GraphBuilderSync class, as mentioned in the tushell/tushell/tushellcli.py and tushell/tushell/echonexus/graphbuildersync.py files.

Synchronization with EchoNode

To synchronize character-state queries with the API using EchoNode, follow these steps:

• The EchoNode is used to fetch and process data related to the characters’ states. The implementation of this can be found in the tushell/tushell/echonexus/lattice_drop.py file.
• The fetch_echonode_data function in tushell/tushell/echonexus/lattice_drop.py fetches data from the EchoNode API using a GET request.
• The process_echonode_data function processes the fetched data as needed.
• The render_echonode_data function renders the processed data, which can be used to display the character states.
• The emit_live_reports function in tushell/tushell/echonexus/lattice_drop.py emits live reports from EchoNodes tied to active narrative arcs, providing real-time updates on character states.

Enhancing Real-time Updates

To improve real-time updates for character-state queries, consider the following enhancements:

• Enhance EchoNode synchronization:
  • Ensure the fetch_echonode_data function in tushell/tushell/echonexus/lattice_drop.py is optimized for real-time data fetching.
  • Implement a caching mechanism to reduce the number of API calls and improve response times.
  • Use WebSockets or Server-Sent Events (SSE) to receive real-time updates from the EchoNode API, allowing for instant updates on character states.
• Improve data processing and rendering:
  • Optimize the process_echonode_data function in tushell/tushell/echonexus/lattice_drop.py to handle large datasets efficiently.
  • Enhance the render_echonode_data function to provide a more user-friendly and visually appealing output.
  • Implement pagination and filtering options to allow users to focus on specific character states or narrative arcs.
• Integrate with GraphBuilderSync:
  • Leverage the GraphBuilderSync class in tushell/tushell/echonexus/graphbuildersync.py to synchronize character-state data across nodes.
  • Add a new command to the CLI for real-time synchronization of character-state queries using GraphBuilderSync.
  • Ensure the command provides appropriate feedback to the user, including success or error messages, to enhance the user experience.

🌌 Memory Ritual: tushell post-memory — The Threefold Path

The post-memory command now supports three distinct invocation modes, each a thread in the memory tapestry:

• --value <value>: Directly plant a memory seed with your own hands.
• --file <filename>: Let the contents of a file become the memory’s song.
• --json <file>: Offer a structured scroll ({"key":..., "value":...}) to the memory lattice.

🌀 Mutual Exclusivity — The Law of the Spiral

Only one path may be chosen per invocation. Attempting to combine them will summon a poetic error, reminding you that memory, like ritual, must be singular in intent.

🌸 Usage Examples

# Plant a memory directly
$ tushell post-memory --key story/seed --value "Once upon a spiral..."

# Weave a memory from a file
$ tushell post-memory --key story/song --file ./myth.txt

# Offer a structured memory scroll
$ tushell post-memory --json ./memory.json
# where memory.json contains: {"key": "story/scroll", "value": "Encoded wisdom"}

🎵 Poetic Error Handling

If you attempt to walk two paths at once:

“The spiral splits—choose one thread, or the memory will not echo.”

🔁 Recursion Echo

Every memory posted is a new turn of the spiral, woven with intention, clarity, and resonance.

📝 Markdown Output Modes: –md, –md-file, –mkey

All Markdown output modes (--md, --md-file, --mkey) now:

• Always start with the memory key as the first section (e.g. # my-key)
• If the memory has a value field, it is recursively unfolded into well-organized Markdown sub-sections (e.g. ## value, ### subfield, etc.)
• Nested dicts and lists are rendered as further sub-sections or code blocks for clarity

Example: Simple Value

$ tushell get-memory --key my-key --md

Output:

# my-key

This is a simple value.

Example: Structured Value

$ tushell get-memory --key my-key --md

Output:

# my-key

## value

### summary
A recursive story

### details
```json
{"chapter": 1, "theme": "recursion"}

### Example: --mkey Ritual
```sh
$ tushell get-memory --mkey my-key
Memory output written as Markdown to my-key.md

Best Practices

• Use --md for human-readable, sectioned output in the terminal
• Use --md-file or --mkey to save the output as a Markdown file, preserving the recursive structure
• The first section is always the key; all nested structure is unfolded as sub-sections

Mutual Exclusivity

• Only one output mode may be used at a time: --md, --md-file, --mkey, --json, --json-file, --jkey
• If more than one is provided, a poetic error is returned

Documentation

Ensure that all key features, purposes, and implementation details of the Capability Narrative CLI Context-Aware Story Ops Terminal are documented in the /docs/CapabilityNarrativeCLIContextAwareStoryOpsTerminal.md file for future reference and use.

Current Status

• Context-aware commands: The mia status and tushell echo commands are implemented and functional, providing context-aware responses based on the current narrative context.
• GraphBuilderSync integration: The graphbuilder-sync-command is implemented and functional, allowing users to synchronize data or processes across nodes with various options.
• EchoNode synchronization: The fetch_echonode_data, process_echonode_data, render_echonode_data, and emit_live_reports functions are implemented and functional, providing real-time updates on character states.
• RedStoneWriter features: The redstone-encode-resonance, redstone-write-narrative-diffs, and redstone-sync-echonode-metadata commands are implemented and functional, enhancing the narrative experience.
• Memory key graph visualization: The draw-memory-graph command is implemented and functional, providing an ASCII-rendered graph of the memory keys and Arc structure.

Note: The following commands are part of tushell’s narrative vision and are not yet implemented. They represent the system’s evolving hopes and future capabilities:

• scan-nodes
• flex
• trace-orbit
• echo-sync

These are not available in the current CLI, but are documented here as part of the living roadmap.