Glyph-Native Shell Integration — Path to Where We Want to Be
# Glyph-Native Shell Integration — Path to Where We Want to Be
## Invocation
The shell is a ring. Portal is the source.
The goal is not merely to have `hx` installed and callable. The goal is to make glyph-led Portal commands feel native in the shell while keeping ordinary shell behavior intact.
This means arriving at a state where:
- the shell boots through Portal - Portal emits the shell law during init - sacred glyphs are sufficient to mark a command as Portal-native - ordinary shell commands remain ordinary shell commands - the shell does not become the source of truth - `hex-init.sh` stays thin - `▼ init` becomes the place where command behavior is taught to the shell
This is the path.
---
## Current State
The current shell already proves several important things:
### 1. The shell enters through Portal bootstrap
`~/.zshrc` sources `hex-init.sh`.
That means the shell is already being prepared through a Portal-aware layer rather than by scattered ad hoc shell customizations.
### 2. `hx` is already the fast path
`hex-init.sh` prefers:
- socket present → `hx '▼ init'` - no socket but portal exists → `portal --daemon '▼ init'` - no Portal at all → plain shell fallback
This is good architecture.
It means the shell already knows how to ask Portal to initialize it.
### 3. Portal already returns shell code
The key move is:
```bash eval "$($HX_CMD '▼ init' 2>/dev/null)" ```
This means Portal is already allowed to emit shell code back into the live shell context.
That is the gate.
Because once Portal can emit: - prompt code - color setup - aliases - shell functions - hooks
it can also emit: - glyph dispatch functions - preexec handlers - zle widgets - line routers
This means the desired future is not hypothetical. The architecture is already open to it.
---
## The Desired State
We want the shell to reach a condition where glyph-led commands are self-identifying as Portal commands.
Examples of the desired experience:
```bash ▲ mesh repo push △ gaps 10 ▲ fid gap done gem-chord-alignment gca-005 ```
without having to explicitly type:
```bash hx '▲ mesh repo push' ```
The shell should understand that the leading glyph marks the command as belonging to Portal command language.
But the shell itself should not become clever by independent force.
Instead:
**Portal teaches the shell how to recognize Portal commands.**
That is the difference that preserves sovereignty.
---
## Core Law
**The glyph is the ritual prefix.** **The prefix is the dispatch signal.** **Portal owns the rule.** **The shell obeys the emitted rule.**
Not:
- Bash intrinsically understands sacred glyphs
But:
- Portal emits shell behavior such that sacred glyphs route into HX parsing
This keeps the shell as ring and Portal as source.
---
## Architecture We Want
### Layer I — `hex-init.sh` remains minimal
`hex-init.sh` should continue doing only the following:
- locate HEXCRAFT root - locate `portal` - locate `hx` - prefer socket-first initialization - fall back to daemon spawn if needed - keep PATH concerns local to shell bootstrap - define shell-only sourced helpers like `bones`
It should **not** become the place where full command language is hardcoded.
That would thicken the ring and weaken the source.
### Layer II — `▼ init` becomes the shell law emitter
The command:
```bash hx '▼ init' ```
should emit everything the shell needs to behave as a Portal-aware ring.
This includes:
- prompt - aliases - colors - greeting hooks if desired - glyph dispatch behavior - any shell integration needed for native ritual command handling
This is the correct place for shell command behavior because it keeps the logic in Portal rather than in shell bootstrap files.
### Layer III — glyph dispatch is installed into the shell
Portal should emit shell code that gives the shell one new capability:
**If a command line begins with a sacred glyph, route it to HX.**
Everything else should remain ordinary shell behavior.
This can be achieved in stages.
---
## The Implementation Path
## Stage 1 — Explicit helper path
Begin with a simple Portal-emitted shell function that routes glyph-led commands into `hx`.
For example in spirit:
```bash portal_dispatch() { case "$1" in [▲△◆▼⬢]*) hx "$*" ;; *) command "$@" ;; esac } ```
This is not necessarily the final shape, but it proves the concept cheaply.
The important thing is not the exact function name. The important thing is proving that glyph detection and routing can be emitted by `▼ init`.
At this stage, use is still somewhat explicit.
This proves: - shell context is correct - glyph detection works - Portal command lines can be routed cleanly - no ordinary shell behavior is broken
### Why start here
Because it is debuggable. Because it keeps failure local. Because it establishes the law before attempting magic.
---
## Stage 2 — Native-feeling line interception
Once the explicit helper works, move to shell-native interception so that raw entered lines beginning with glyphs are routed automatically.
For zsh, this likely means one of:
- `preexec`/`precmd`-style interception - `zle` widget integration - wrapped accept-line behavior - Portal-emitted shell function that examines the buffer before execution
The law remains the same:
- glyph-led line → Portal command - ordinary line → ordinary shell
The shell should not reinterpret every line as Portal. Only lines clearly marked by the sacred prefix should be routed.
### Why this is the real target
Because it lets:
```bash ▲ mesh repo push ```
feel native.
That is where command language stops feeling like an external tool and starts feeling like a first-class ritual layer.
---
## Stage 3 — Parser discipline and raw-line capture
Once raw glyph lines are being intercepted, the next concern is correctness.
Portal command lines must be captured **before shell expansion** wherever possible.
Why this matters:
- spaces - quotes - globbing - pipes - redirects - variable expansion
can all distort command meaning if the shell mutates the line before Portal sees it.
So the ideal path is:
- shell sees raw line - shell detects sacred prefix - shell passes raw line to `hx` - `hx` parses it according to Portal law
This keeps parsing sovereign.
---
## Stage 4 — Canonized glyph table
Once dispatch exists, the glyph set must be made explicit and stable.
This means Portal should own a known dispatch rune set, such as:
- `▲` - `△` - `◆` - `▼` - `⬢`
or whatever the final canonical set becomes.
The shell should not guess arbitrarily. It should only route when the first token clearly begins with a canonized Portal prefix.
This gives: - predictability - no accidental collisions - stable ritual language - easier teaching - easier testing
---
## Stage 5 — Fallback and safety behavior
The shell must behave safely in all failure conditions.
If socket exists: - use `hx`
If socket does not exist but Portal can spawn: - spawn and continue
If Portal is absent: - ordinary shell remains usable
If glyph routing is installed but Portal is unavailable: - fail clearly and locally - do not corrupt the ordinary shell
This means glyph routing should degrade gracefully: - either report that Portal is unavailable - or deliberately fall back to explicit `hx`/`portal` error behavior
The shell must never become unusable because the sacred path is temporarily absent.
---
## Practical Implementation Guidelines
### 1. Keep `hex-init.sh` thin Do not bake glyph parsing deeply into `hex-init.sh`.
It should remain bootstrap, not doctrine.
### 2. Move command behavior into `▼ init` If the shell must learn something, `▼ init` should teach it.
### 3. Start with explicit dispatch Prove the routing path before making the shell magical.
### 4. Then add native interception Only after the explicit path is stable.
### 5. Capture lines before shell expansion where possible This preserves the Portal command body.
### 6. Treat the glyph set as canon Not as loose decoration.
### 7. Keep normal shell behavior sacred too Ordinary shell commands must remain plain shell commands.
This is not about replacing the shell with ambiguity. It is about adding a clearly marked Portal-native command layer.
---
## What Success Looks Like
The desired end-state looks like this:
### On shell boot - `.zshrc` sources `hex-init.sh` - `hex-init.sh` asks Portal for shell bootstrap via `▼ init` - Portal emits: - prompt - aliases - colors - glyph dispatch law
### During shell use - ordinary command: ```bash ls -la ``` behaves as ordinary shell
- sacred command: ```bash ▲ mesh repo push ``` is routed to Portal automatically
### In failure conditions - shell remains usable - errors remain local and understandable - the ring does not collapse because the source is absent
That is the operational shape we want.
---
## Testing Path
Implementation should be tested in this order:
### 1. Bootstrap correctness - does `hex-init.sh` find the right binary/socket? - does `▼ init` emit valid shell code?
### 2. Explicit dispatch correctness - can a helper function correctly route glyph-led commands to `hx`?
### 3. Raw-line interception correctness - can a raw glyph-led line be captured and routed before accidental shell mutation?
### 4. Non-glyph command safety - do plain shell commands behave exactly as before?
### 5. Failure mode safety - what happens when socket disappears? - what happens when `hx` is missing? - what happens when Portal cannot spawn?
### 6. Quoting and parsing edge cases - quoted arguments - spaces - punctuation - pipes - redirects - variables
This path keeps the ritual layer honest.
---
## The Final Law
**Portal is the source.** **The shell is the ring.** **Glyphs mark sacred command language.** **`▼ init` teaches the ring how to recognize them.**
That is how we get where we want to be.
Not by making the shell inherently magical, but by letting Portal emit the law that the shell follows.