−
100%
+
fit
scroll
# 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.
△