fux-engine 0.3.0__tar.gz → 0.3.2__tar.gz

{fux_engine-0.3.0/fux_engine.egg-info → fux_engine-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fux-engine
-Version: 0.3.0
+Version: 0.3.2
 Summary: Fux — a portable agent-aware knowledge engine: rules, memory, narrative, and graph in one frontmatter substrate.
 Author-email: arpit arya <arpitarya.me@gmail.com>
 License: MIT
@@ -115,6 +115,13 @@ fux serve                      # local dashboard over the generated views
 fux import docs/               # migrate existing markdown → narrative entries
 fux parity                     # is it safe to retire the old graph/docs/memory?
 fux tour                       # ordered ONBOARDING.md
+
+# Runtime consumers (agents + apps, e.g. Anton's Orff concierge)
+fux components [--scope dir]   # component/hook registry for on-the-fly UI generation
+fux validate-spec              # validate a declarative UISpec against the registry
+fux feedback                   # record rejected specs as candidate vocabulary gaps
+fux hook-recall                # stdin-JSON recall for agent prompt hooks
+fux query / path / explain     # graph traversal: cross-module "how does X relate to Y"
 ```
 
 **Complete, example-driven guide to everything Fux does:
@@ -180,6 +187,12 @@ effective ruleset = ~/.claude/fux/global/   (cross-project best practices)
 `project` overrides `pack` overrides `global`. `fux check` flags conflicts
 instead of silently shadowing.
 
+> Packs are optional. A single-project setup can keep `packs = []` and hold all
+> authored knowledge in the repo's own `.fux/` — version-controlled with the code
+> it governs (see Anton's `knowledge-location` rule for the reasoning). Global
+> rules are seeded from this repo's `fux/data/global/`, so they stay versioned
+> tool code, not loose documents.
+
 ## Guarantee
 
 Every maintenance command is shell/AST/parse — **no LLM calls**. The only paths

{fux_engine-0.3.0 → fux_engine-0.3.2}/README.md

@@ -76,6 +76,13 @@ fux serve                      # local dashboard over the generated views
 fux import docs/               # migrate existing markdown → narrative entries
 fux parity                     # is it safe to retire the old graph/docs/memory?
 fux tour                       # ordered ONBOARDING.md
+
+# Runtime consumers (agents + apps, e.g. Anton's Orff concierge)
+fux components [--scope dir]   # component/hook registry for on-the-fly UI generation
+fux validate-spec              # validate a declarative UISpec against the registry
+fux feedback                   # record rejected specs as candidate vocabulary gaps
+fux hook-recall                # stdin-JSON recall for agent prompt hooks
+fux query / path / explain     # graph traversal: cross-module "how does X relate to Y"
 ```
 
 **Complete, example-driven guide to everything Fux does:
@@ -141,6 +148,12 @@ effective ruleset = ~/.claude/fux/global/   (cross-project best practices)
 `project` overrides `pack` overrides `global`. `fux check` flags conflicts
 instead of silently shadowing.
 
+> Packs are optional. A single-project setup can keep `packs = []` and hold all
+> authored knowledge in the repo's own `.fux/` — version-controlled with the code
+> it governs (see Anton's `knowledge-location` rule for the reasoning). Global
+> rules are seeded from this repo's `fux/data/global/`, so they stay versioned
+> tool code, not loose documents.
+
 ## Guarantee
 
 Every maintenance command is shell/AST/parse — **no LLM calls**. The only paths

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/__init__.py

@@ -3,4 +3,4 @@
 One frontmatter substrate → derived index, graph, and memory views.
 $0 deterministic maintenance; no mandatory LLM calls. See docs/fux-plan.md.
 """
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/assets/graph_boot.js

@@ -42,6 +42,8 @@ for (const e of edges){ const a=byId[e.source], b=byId[e.target];
     (govTargets[kn.id]=govTargets[kn.id]||[]).push({id:other.id, type:e.type}); }
 
 let view = { x: 0, y: 0, k: 1 }, hidden = new Set(), hiddenE = new Set();
+let vTarget = null;           // when set, the camera eases toward it (smooth zoom/fly)
+const VIEW_EASE = 0.2;        // per-frame approach fraction toward vTarget
 let selected = null, hover = null, query = "", lens = "know";
 let running = true, showLabels = true, focusSet = null;
 let pathMode = false, pathA = null, pathSet = null, pathEdge = new Set(), pathMD = null;
@@ -135,7 +137,7 @@ function updateHits(){ if(!query){ $("qhits").innerHTML=""; return; }
     + (m.length>14 ? `<div class="ct" style="padding:5px 7px">+${m.length-14} more</div>` : "");
   $("qhits").querySelectorAll("[data-jump]").forEach(el => el.onclick = () => jumpTo(el.dataset.jump)); }
 function jumpTo(id){ const n=byId[id]; if(!n) return; selected=id; clearPath(); showDetail(n);
-  if(view.k<1) view.k=1; view.x=-n.x*view.k; view.y=-n.y*view.k; }
+  const k=Math.max(view.k,1); flyTo(-n.x*k, -n.y*k, k); }
 
 // ---- copy / governance footer buttons ----
 $("bcopy").onclick = () => { if(pathSet && pathMD) copy(pathMD(), "path copied");
@@ -151,10 +153,10 @@ $("railtab").onclick = () => { $("right").classList.toggle("collapsed"); applyRi
 applyRightState();   // honour the default-collapsed markup on load
 // Micro / Macro both show the real nodes — they just change zoom. Micro zooms in
 // (centred on the selection if any); Macro fits the whole graph as an overview.
-$("bmicro").onclick = () => { focusSet=null; userMoved=true; const z=Math.max(view.k,1.3); const p=selected&&byId[selected];
-  view.k=z; if(p){ view.x=-p.x*z; view.y=-p.y*z; } };
+$("bmicro").onclick = () => { focusSet=null; const z=Math.max(view.k,1.3); const p=selected&&byId[selected];
+  if(p) flyTo(-p.x*z, -p.y*z, z); else zoomToCenter(z); };
 // Macro = the auto-framed overview; re-enable auto-fit so it stays framed on resize.
-$("bmacro").onclick = () => { focusSet=null; userMoved=false; query=""; $("q").value=""; updateHits(); clearPath(); fit(); };
+$("bmacro").onclick = () => { focusSet=null; userMoved=false; query=""; $("q").value=""; updateHits(); clearPath(); fitAnimated(); };
 
 // ---- layout & geometry --------------------------------------------------
 let W=0, H=0;
@@ -201,7 +203,7 @@ function step(){
     if(c){ n.vx+=(c.x-n.x)*COMM_PULL*alpha; n.vy+=(c.y-n.y)*COMM_PULL*alpha; }
     n.vx*=.85; n.vy*=.85; n.x+=n.vx*0.5; n.y+=n.vy*0.5;
     n.vx-=n.x*GRAVITY*alpha; n.vy-=n.y*GRAVITY*alpha; }
-  alpha *= ALPHA_DECAY; if(alpha < ALPHA_MIN){ alpha = 0; running = false; if(!userMoved) fit(); }
+  alpha *= ALPHA_DECAY; if(alpha < ALPHA_MIN){ alpha = 0; running = false; if(!userMoved && !vTarget) fit(); }
 }
 const TC = (wx,wy) => ({ x: wx*view.k+W/2+view.x, y: wy*view.k+H/2+view.y });
 const T = n => TC(n.x, n.y);
@@ -213,13 +215,16 @@ const baseR = n => isKnow(n) ? (3 + (n.centrality||0)*3.4 + Math.min((deg[n.id]|
 const radius = n => baseR(n) * Math.min(2.4, Math.max(0.7, view.k));
 const neighbors = id => new Set(adj[id].map(([t])=>t));
 
-function fit(){ const vis = nodes.filter(visible); if(!vis.length) return;
+function fitView(){ const vis = nodes.filter(visible); if(!vis.length) return null;
   const xs=vis.map(n=>n.x).sort((a,b)=>a-b), ys=vis.map(n=>n.y).sort((a,b)=>a-b);
   const lo=i=>i[Math.floor(i.length*0.02)], hi=i=>i[Math.floor(i.length*0.98)];
   const minX=lo(xs),maxX=hi(xs),minY=lo(ys),maxY=hi(ys);
   const w=maxX-minX||1, h=maxY-minY||1;
-  view.k = Math.max(0.2, Math.min(2.5, 0.85*Math.min(W/w, H/h)));
-  view.x = -(minX+maxX)/2*view.k; view.y = -(minY+maxY)/2*view.k; }
+  const k = Math.max(0.2, Math.min(2.5, 0.85*Math.min(W/w, H/h)));
+  return { k, x:-(minX+maxX)/2*k, y:-(minY+maxY)/2*k }; }
+// fit() snaps (used by the settling physics loop); fitAnimated() glides (user-driven).
+function fit(){ const t=fitView(); if(t){ view.k=t.k; view.x=t.x; view.y=t.y; vTarget=null; } }
+function fitAnimated(){ const t=fitView(); if(t) vTarget={...t}; }
 function setFocus(id){ focusSet = new Set([id, ...neighbors(id)]); reheat(0.45); }
 function clearFocus(){ focusSet = null; reheat(0.3); }
 function toggleLens(){ const knowOn = focusSet && focusSet._lens;
@@ -249,11 +254,13 @@ function clearPath(){ pathSet=null; pathEdge=new Set(); pathA=null; pathMD=null;
 // ---- render : the Solar pipeline ----------------------------------------
 function draw(){
   _f++;
+  easeView();
   if(running && _f % PHYS_STRIDE === 0) step();
   // The layout grows as it settles, so keep re-framing to fit (driven by the draw
   // loop, not events) until the user takes control — this is the real fix for the
-  // "graph is cut off until I switch tabs" glitch.
-  if(running && !userMoved && _f % 16 === 0) fit();
+  // "graph is cut off until I switch tabs" glitch. Suppressed while a camera tween
+  // is in flight, so the auto-fit and the glide never fight.
+  if(running && !userMoved && !vTarget && _f % 16 === 0) fit();
   ctx.clearRect(0,0,W,H);
   const anchor = selected || hover, near = anchor ? neighbors(anchor) : null;
   const dimCode = lens==="know";
@@ -370,19 +377,46 @@ function bindMM(mm){ if(!mm) return;
   const panTo = ev => { if(!_mmBounds) return; const r=mm.getBoundingClientRect();
     const wx=((ev.clientX-r.left)-_mmBounds.ox)/_mmBounds.s, wy=((ev.clientY-r.top)-_mmBounds.oy)/_mmBounds.s;
     view.x=-wx*view.k; view.y=-wy*view.k; };
-  mm.onmousedown = e => { panTo(e); const mv=ev=>panTo(ev);
+  mm.onmousedown = e => { vTarget=null; panTo(e); const mv=ev=>panTo(ev);
     const up=()=>{ window.removeEventListener("mousemove",mv); window.removeEventListener("mouseup",up); };
     window.addEventListener("mousemove",mv); window.addEventListener("mouseup",up); }; }
 bindMM($("mm")); bindMM($("fmm"));
 
 // ---- zoom well + mode pill ----------------------------------------------
 const K_MIN=0.15, K_MAX=5, LK=Math.log(K_MIN), LKR=Math.log(K_MAX)-LK;
+const clampK = k => Math.max(K_MIN, Math.min(K_MAX, k));
+// Smooth camera. Every interactive zoom/recenter sets `vTarget`; easeView() (run
+// once per frame in draw) glides the live `view` toward it, so nothing snaps.
+// Direct manipulation — panning, node-drag, the zoom slider — cancels the tween so
+// it stays 1:1 with the cursor; the physics auto-fit is suppressed while one runs.
+function easeView(){ if(!vTarget) return;
+  view.k += (vTarget.k-view.k)*VIEW_EASE;
+  view.x += (vTarget.x-view.x)*VIEW_EASE;
+  view.y += (vTarget.y-view.y)*VIEW_EASE;
+  if(Math.abs(vTarget.k-view.k)<1e-3 && Math.hypot(vTarget.x-view.x, vTarget.y-view.y)<0.4){
+    view.k=vTarget.k; view.x=vTarget.x; view.y=vTarget.y; vTarget=null; } }
+// Zoom keeping the world point under (ex,ey) pinned — compounded in target space so
+// rapid wheel ticks anchor consistently while the previous glide is still in flight.
+function zoomBy(ex, ey, factor){ userMoved=true; const b=vTarget||view; const k=clampK(b.k*factor);
+  const wx=(ex-W/2-b.x)/b.k, wy=(ey-H/2-b.y)/b.k;
+  vTarget={ k, x: ex-W/2-wx*k, y: ey-H/2-wy*k }; }
+function zoomToCenter(k){ userMoved=true; const b=vTarget||view; k=clampK(k);
+  const wx=-b.x/b.k, wy=-b.y/b.k; vTarget={ k, x:-wx*k, y:-wy*k }; }
+function flyTo(x, y, k){ userMoved=true; vTarget={ k:clampK(k), x, y }; }
 function updatePill(){ const macro = view.k < 0.55;   // zoomed-out overview = macro
   $("bmacro").classList.toggle("on",macro); $("bmicro").classList.toggle("on",!macro);
-  $("zthumb").style.left=((Math.log(Math.max(K_MIN,Math.min(K_MAX,view.k)))-LK)/LKR*100)+"%";
+  $("zthumb").style.left=((Math.log(clampK(view.k))-LK)/LKR*100)+"%";
   $("zlabel").textContent = macro ? "macro" : (view.k>1.4 ? "detail" : "micro"); }
-$("ztrack").onclick = e => { userMoved=true; const r=$("ztrack").getBoundingClientRect();
-  view.k = Math.exp(LK + Math.max(0,Math.min(1,(e.clientX-r.left)/r.width))*LKR); };
+// Zoom slider: drag (not just click) the thumb. Writes the camera directly so the
+// thumb tracks the cursor 1:1, recentred on the viewport so the graph scales in place.
+const kFromTrack = clientX => { const r=$("ztrack").getBoundingClientRect();
+  return Math.exp(LK + Math.max(0,Math.min(1,(clientX-r.left)/r.width))*LKR); };
+function zoomCenterNow(k){ userMoved=true; vTarget=null; k=clampK(k);
+  const wx=-view.x/view.k, wy=-view.y/view.k; view.k=k; view.x=-wx*k; view.y=-wy*k; }
+$("ztrack").onmousedown = e => { e.preventDefault(); zoomCenterNow(kFromTrack(e.clientX));
+  const mv=ev=>zoomCenterNow(kFromTrack(ev.clientX));
+  const up=()=>{ window.removeEventListener("mousemove",mv); window.removeEventListener("mouseup",up); };
+  window.addEventListener("mousemove",mv); window.addEventListener("mouseup",up); };
 
 // ---- governance ledger --------------------------------------------------
 (function buildLedger(){
@@ -404,17 +438,17 @@ $("ztrack").onclick = e => { userMoved=true; const r=$("ztrack").getBoundingClie
     if(e.target.closest(".tgt")) return;
     body.querySelectorAll(".lrow").forEach(x=>x.classList.remove("open")); row.classList.add("open");
     const n=byId[row.dataset.rule]; selected=n.id; clearPath(); showDetail(n);
-    if(view.k<1) view.k=1.1; view.x=-n.x*view.k; view.y=-n.y*view.k; }; });
+    const k=Math.max(view.k,1.1); flyTo(-n.x*k, -n.y*k, k); }; });
   body.querySelectorAll(".tgt").forEach(t => { t.onclick = () => { const n=byId[t.dataset.go];
-    if(!n) return; selected=n.id; clearPath(); showDetail(n); if(view.k<1) view.k=1.1;
-    view.x=-n.x*view.k; view.y=-n.y*view.k; }; });
+    if(!n) return; selected=n.id; clearPath(); showDetail(n);
+    const k=Math.max(view.k,1.1); flyTo(-n.x*k, -n.y*k, k); }; });
 })();
 
 // ---- interaction --------------------------------------------------------
 function hit(mx,my){ let best=null,bd=1e9; for(const n of nodes){ if(!visible(n)) continue; const p=T(n);
   const d=Math.hypot(mx-p.x,my-p.y); if(d < radius(n)+4 && d<bd){ bd=d; best=n; } } return best; }
 let drag=null, pan=false, last=null, downAt=null;
-cv.onmousedown = e => { last={x:e.offsetX,y:e.offsetY}; downAt={x:e.offsetX,y:e.offsetY};
+cv.onmousedown = e => { vTarget=null; last={x:e.offsetX,y:e.offsetY}; downAt={x:e.offsetX,y:e.offsetY};
   const n=hit(e.offsetX,e.offsetY);
   if(pathMode){ if(n){ if(!pathA){ pathA=n.id; selected=n.id; showDetail(n); toast("now click the target node"); }
       else { setPath(shortestPath(pathA,n.id)); pathA=null; togglePath(); } } return; }
@@ -433,13 +467,19 @@ cv.onmousemove = e => {
   last={x:e.offsetX,y:e.offsetY}; };
 window.addEventListener("mouseup", () => { drag=null; pan=false; });
 cv.ondblclick = e => { const n=hit(e.offsetX,e.offsetY); if(n){ selected=n.id; setFocus(n.id); showDetail(n); } };
-cv.onwheel = e => { e.preventDefault(); userMoved=true; const f=e.deltaY<0?1.1:0.9;
-  const mx=e.offsetX-W/2-view.x, my=e.offsetY-H/2-view.y;
-  view.k=Math.max(K_MIN,Math.min(K_MAX,view.k*f)); view.x-=mx*(f-1); view.y-=my*(f-1); };
+// Wheel/trackpad zoom: scale by the *magnitude* of the delta (normalised across
+// pixel/line/page deltaModes) so one mouse notch and a trackpad swipe both feel
+// natural, then glide there. macOS pinch arrives as ctrl+wheel with coarser deltas.
+cv.onwheel = e => { e.preventDefault();
+  let d = e.deltaY; if(e.deltaMode===1) d*=16; else if(e.deltaMode===2) d*=(H||500);
+  const factor = Math.max(0.4, Math.min(2.5, Math.exp(-d * (e.ctrlKey ? 0.010 : 0.0018))));
+  zoomBy(e.offsetX, e.offsetY, factor); };
 window.addEventListener("keydown", e => { if(e.target.tagName==="INPUT"){ if(e.key==="Escape")e.target.blur(); return; }
   const k=e.key.toLowerCase();
   if(k==="/"){ e.preventDefault(); $("q").focus(); }
-  else if(k==="f"){ userMoved=false; fit(); } else if(k==="r"){ userMoved=true; view={x:0,y:0,k:1}; }
+  else if(k==="f"){ userMoved=false; fitAnimated(); } else if(k==="r"){ flyTo(0,0,1); }
+  else if(k==="+"||k==="="){ zoomToCenter((vTarget?vTarget.k:view.k)*1.3); }
+  else if(k==="-"||k==="_"){ zoomToCenter((vTarget?vTarget.k:view.k)/1.3); }
   else if(k===" "){ e.preventDefault(); running ? (running=false) : reheat(0.3); }
   else if(k==="e"){ if(selected) setFocus(selected); }
   else if(k==="l"){ showLabels=!showLabels; }

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/assets/graph_template.html

@@ -262,7 +262,7 @@
         <div class="lab">Edge language</div>
         <div id="efilters"></div>
       </div>
-      <div class="keyhint"><span><b>/</b>search</span><span><b>e</b>focus</span><span><b>c</b>macro</span><span><b>p</b>path</span><span><b>l</b>labels</span><span><b>Esc</b>clear</span></div>
+      <div class="keyhint"><span><b>/</b>search</span><span><b>±</b>zoom</span><span><b>f</b>fit</span><span><b>e</b>focus</span><span><b>c</b>macro</span><span><b>p</b>path</span><span><b>l</b>labels</span><span><b>Esc</b>clear</span></div>
     </div>
     <div class="zoomwell">
       <span class="lab" style="font-size:10px;letter-spacing:.12em;text-transform:uppercase">Zoom</span>

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/costledger.py

@@ -9,6 +9,10 @@ not just a per-call estimate. Opt-in via `cost_tracking`; recorded on each
 `tokens_without` = reading the governed source file(s) for the matched rules;
 `tokens_with` = the matched Tier-2 rule(s) only (the realistic later-lookup cost,
 since the Tier-1 INDEX is injected once per session). `saved = without − with`.
+
+The summary reports the lifetime total *and* a per-day / per-week / per-month rate
+— `tokens_saved` amortised across the observed span (`first`→`last`, floored at one
+day), then scaled — so the win reads as an ongoing throughput, not just a total.
 """
 from __future__ import annotations
 
@@ -104,16 +108,45 @@ def overall_ratio(led: dict) -> float:
     return (led.get("tokens_without", 0) / w) if w else 0.0
 
 
+_AVG_MONTH = 365.25 / 12  # mean calendar month, in days
+
+
+def _date(s: str | None) -> _dt.date | None:
+    try:
+        return _dt.date.fromisoformat(s) if s else None
+    except ValueError:
+        return None
+
+
+def span_days(led: dict) -> int:
+    """Calendar days spanned by the recorded lookups (floored at 1, so a same-day
+    ledger still yields a finite per-day rate rather than dividing by zero)."""
+    a, b = _date(led.get("first")), _date(led.get("last"))
+    return max(1, (b - a).days) if a and b else 1
+
+
+def rates(led: dict) -> dict:
+    """Average tokens saved per day / week / month over the observed span — the
+    lifetime `tokens_saved` amortised across `span_days`, then scaled up."""
+    days = span_days(led)
+    per_day = led.get("tokens_saved", 0) / days
+    return {"days": days, "day": per_day, "week": per_day * 7, "month": per_day * _AVG_MONTH}
+
+
 def render_summary(led: dict) -> str:
     if not led.get("lookups"):
         return ""
     span = led.get("first") or "?"
     ratio = overall_ratio(led)
     x = f"{ratio:.1f}×" if ratio else "—"
+    r = rates(led)
     return "\n".join([
         "",
         f"Cumulative (tracked across {led['lookups']} lookup(s) since {span})",
         f"  tokens without Fux:  {led['tokens_without']:>10,} tok",
         f"  tokens with Fux:     {led['tokens_with']:>10,} tok",
         f"  tokens saved:        {led['tokens_saved']:>10,} tok   → {x} overall",
+        f"  {'≈ saved per day:':<21}{round(r['day']):>10,} tok   (avg over {r['days']} day(s))",
+        f"  {'≈ saved per week:':<21}{round(r['week']):>10,} tok",
+        f"  {'≈ saved per month:':<21}{round(r['month']):>10,} tok",
     ])

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/hookinstall.py

@@ -1,8 +1,8 @@
 """`fux hooks install` — wire Fux across every agent surface from one command.
 
-Four surfaces, all pointing at the *installed package* scripts (~/.claude/fux/hooks),
-never a sibling dev checkout:
-  git      → .git/hooks/pre-commit shim → packaged pre_commit.sh (build + stage views)
+Four surfaces, all invoking the *installed* `fux` console script — the package is
+the single source of truth, no copied wrapper scripts or dev-checkout paths:
+  git      → .git/hooks/pre-commit (self-contained: `fux build` + stage views)
   claude   → .claude/settings.json      (SessionStart/PostToolUse/Stop hooks)
   codex    → .codex/hooks.json
   copilot  → .copilot/settings.json
@@ -13,22 +13,28 @@ from __future__ import annotations
 import stat
 from pathlib import Path
 
-from fux import gitutil, paths, settings
+from fux import gitutil, settings
 
 SURFACES = ["git", "claude", "codex", "copilot"]
 _MARK = "fux-hook"
 
-
-def _packaged_precommit() -> Path:
-    return paths.claude_home() / "fux" / "hooks" / "pre_commit.sh"
-
-
-def _shim(target: Path) -> str:
-    return (f"#!/bin/sh\n# {_MARK} — installed by `fux hooks install`. Delegates to the\n"
-            f"# packaged Fux pre-commit (build derived views + stage them).\n"
-            f'HOOK="{target}"\n'
-            '[ -x "$HOOK" ] && exec "$HOOK" "$@"\n'
-            'exit 0\n')
+# Self-contained pre-commit: resolve `fux` (or `python -m fux`), then rebuild the
+# derived views and stage them so .fux/out/ matches the committed code in the same
+# commit. Non-blocking; skips during rebase/merge. No external script reference.
+_SHIM = f"""#!/bin/sh
+# {_MARK} — installed by `fux hooks install`. Rebuild + stage .fux/out/ ($0).
+if command -v fux >/dev/null 2>&1; then FUX="fux"; else
+  PY="${{FUX_PYTHON:-$(command -v python3.14 || command -v python3 || command -v python)}}"
+  [ -n "$PY" ] && "$PY" -c "import fux" 2>/dev/null && FUX="$PY -m fux" || exit 0
+fi
+G="$(git rev-parse --git-dir 2>/dev/null || echo .git)"
+[ -d "$G/rebase-merge" ] || [ -d "$G/rebase-apply" ] && exit 0
+[ -f "$G/MERGE_HEAD" ] || [ -f "$G/CHERRY_PICK_HEAD" ] && exit 0
+$FUX context >/dev/null 2>&1 || exit 0
+echo "[fux hook] rebuilding derived views..."
+$FUX build >/dev/null 2>&1 && git add .fux/out 2>/dev/null
+exit 0
+"""
 
 
 def _install_git(root: Path) -> str:
@@ -43,7 +49,7 @@ def _install_git(root: Path) -> str:
         note = f" (existing hook backed up → {backup.name})"
     else:
         note = ""
-    hook.write_text(_shim(_packaged_precommit()), encoding="utf-8")
+    hook.write_text(_SHIM, encoding="utf-8")
     hook.chmod(hook.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
     return f"{hook}{note}"
 

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/paths.py

@@ -80,6 +80,12 @@ class Footprint:
     def out(self) -> Path:
         return self.base / "out"
 
+    @property
+    def sessions(self) -> Path:
+        """Per-session runtime state (gitignored), kept out of ``out/``'s top level
+        so the derived html/reports there stay easy to browse."""
+        return self.base / "out" / "sessions"
+
     @property
     def config(self) -> Path:
         return self.base / "config.toml"

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/settings.py

@@ -2,24 +2,25 @@
 
 Claude (`.claude/settings.json`), Codex (`.codex/hooks.json`), and Copilot
 (`.copilot/settings.json`) share one event→hook shape, so one writer serves all
-three. Prefers the installed wrapper scripts (~/.claude/fux/hooks/*.sh, which carry
-a `python -m fux` fallback) so hooks fire even when the `fux` console script is not
-on PATH; falls back to the bare `fux <subcommand>` form otherwise.
+three. Hooks invoke the installed `fux` **console script** directly (`fux context`,
+`fux hook-touch`, …) — the package is the single source of truth, no copied wrapper
+scripts and no dev-checkout paths baked into a committed settings file. Set
+`FUX_PYTHON`/PATH so `fux` resolves; for a missing-PATH safety net the bundled
+`~/.claude/fux/hooks/*.sh` wrappers (with a `python -m fux` fallback) still ship and
+can be referenced by hand.
 """
 from __future__ import annotations
 
 import json
 from pathlib import Path
 
-from fux import paths
-
-# event → (wrapper script name, bare-command fallback, optional matcher)
+# event → (fux subcommand, optional matcher)
 _SPEC = {
-    "SessionStart": ("session_start.sh", "fux context", None),
-    "PostToolUse": ("post_tool_use.sh", "fux hook-touch", "Edit|Write"),
-    "Stop": ("stop.sh", "fux hook-check", None),
+    "SessionStart": ("fux context", None),
+    "PostToolUse": ("fux hook-touch", "Edit|Write"),
+    "Stop": ("fux hook-check", None),
 }
-_RECALL = {"UserPromptSubmit": ("user_prompt_submit.sh", "fux hook-recall", None)}
+_RECALL = {"UserPromptSubmit": ("fux hook-recall", None)}
 
 # agent → settings file (relative to project root)
 AGENT_FILES = {
@@ -29,28 +30,26 @@ AGENT_FILES = {
 }
 
 
-def _command(script: str, fallback: str) -> str:
-    wrapper = paths.claude_home() / "fux" / "hooks" / script
-    return str(wrapper) if wrapper.exists() else fallback
-
-
-def _entry(script: str, fallback: str, matcher: str | None) -> dict:
-    hook = {"hooks": [{"type": "command", "command": _command(script, fallback)}]}
+def _entry(command: str, matcher: str | None) -> dict:
+    hook = {"hooks": [{"type": "command", "command": command}]}
     if matcher:
         hook["matcher"] = matcher
     return hook
 
 
 def wire_file(path: Path, recall: bool = False) -> Path:
-    """Wire the Fux hook spec into one agent settings file. Idempotent per event."""
+    """Wire the Fux hook spec into one agent settings file. Idempotent, and
+    *migrating*: a re-install rewrites any stale Fux entry (e.g. an old wrapper-script
+    path) to the current `fux <subcommand>` form, leaving foreign hooks untouched."""
     path.parent.mkdir(parents=True, exist_ok=True)
     data = json.loads(path.read_text()) if path.exists() else {}
     hooks = data.setdefault("hooks", {})
     spec = {**_SPEC, **(_RECALL if recall else {})}
-    for event, (script, fallback, matcher) in spec.items():
-        existing = hooks.setdefault(event, [])
-        if not _already(existing):
-            existing.append(_entry(script, fallback, matcher))
+    for event, (command, matcher) in spec.items():
+        kept = [e for e in hooks.get(event, [])
+                if not any("fux" in h.get("command", "") for h in e.get("hooks", []))]
+        kept.append(_entry(command, matcher))
+        hooks[event] = kept
     path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
     return path
 
@@ -87,9 +86,3 @@ def is_wired(path: Path) -> bool:
     hooks = json.loads(path.read_text()).get("hooks", {})
     return any("fux" in h.get("command", "")
                for evs in hooks.values() for e in evs for h in e.get("hooks", []))
-
-
-def _already(existing: list) -> bool:
-    """True if any Fux hook (either wiring form) is already present for this event."""
-    cmds = [h.get("command", "") for e in existing for h in e.get("hooks", [])]
-    return any("fux" in c for c in cmds)

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux/touch.py

@@ -2,7 +2,8 @@
 
 Session-aware: rules whose own source was edited this session are skipped, so the
 PostToolUse hook only nags about rules that drifted, not ones you just updated.
-Session state lives in ``.fux/out/.session-<id>.json`` (gitignored).
+Session state lives in ``.fux/out/sessions/<id>.json`` (gitignored) — tucked in its
+own subdir so it never clutters the derived html/reports at the top of ``out/``.
 """
 from __future__ import annotations
 
@@ -15,8 +16,8 @@ from fux.model import Rule
 
 def _state_path(root: Path, session: str) -> Path:
     fp = paths.Footprint(root)
-    fp.out.mkdir(parents=True, exist_ok=True)
-    return fp.out / f".session-{session or 'default'}.json"
+    fp.sessions.mkdir(parents=True, exist_ok=True)
+    return fp.sessions / f"{session or 'default'}.json"
 
 
 def mark_rule_edited(root: Path, session: str, rule_id: str) -> None:

{fux_engine-0.3.0 → fux_engine-0.3.2/fux_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fux-engine
-Version: 0.3.0
+Version: 0.3.2
 Summary: Fux — a portable agent-aware knowledge engine: rules, memory, narrative, and graph in one frontmatter substrate.
 Author-email: arpit arya <arpitarya.me@gmail.com>
 License: MIT
@@ -115,6 +115,13 @@ fux serve                      # local dashboard over the generated views
 fux import docs/               # migrate existing markdown → narrative entries
 fux parity                     # is it safe to retire the old graph/docs/memory?
 fux tour                       # ordered ONBOARDING.md
+
+# Runtime consumers (agents + apps, e.g. Anton's Orff concierge)
+fux components [--scope dir]   # component/hook registry for on-the-fly UI generation
+fux validate-spec              # validate a declarative UISpec against the registry
+fux feedback                   # record rejected specs as candidate vocabulary gaps
+fux hook-recall                # stdin-JSON recall for agent prompt hooks
+fux query / path / explain     # graph traversal: cross-module "how does X relate to Y"
 ```
 
 **Complete, example-driven guide to everything Fux does:
@@ -180,6 +187,12 @@ effective ruleset = ~/.claude/fux/global/   (cross-project best practices)
 `project` overrides `pack` overrides `global`. `fux check` flags conflicts
 instead of silently shadowing.
 
+> Packs are optional. A single-project setup can keep `packs = []` and hold all
+> authored knowledge in the repo's own `.fux/` — version-controlled with the code
+> it governs (see Anton's `knowledge-location` rule for the reasoning). Global
+> rules are seeded from this repo's `fux/data/global/`, so they stay versioned
+> tool code, not loose documents.
+
 ## Guarantee
 
 Every maintenance command is shell/AST/parse — **no LLM calls**. The only paths

{fux_engine-0.3.0 → fux_engine-0.3.2}/fux_engine.egg-info/SOURCES.txt

@@ -83,7 +83,6 @@ fux/data/global/rules/files-max-100-lines.md
 fux/data/global/rules/no-secrets-in-vcs.md
 fux/data/hooks/_common.sh
 fux/data/hooks/post_tool_use.sh
-fux/data/hooks/pre_commit.sh
 fux/data/hooks/session_start.sh
 fux/data/hooks/stop.sh
 fux/data/hooks/user_prompt_submit.sh

{fux_engine-0.3.0 → fux_engine-0.3.2}/tests/test_costledger.py

@@ -49,3 +49,33 @@ def test_reset_and_summary(project):
     costledger.reset(project)
     assert costledger.load(project)["lookups"] == 0
     assert costledger.render_summary(costledger.load(project)) == ""
+
+
+def test_rates_amortise_over_span(project):
+    _seed(project)
+    from fux import loader, config, paths
+    rules = loader.resolve(project, config.load(paths.Footprint(project).config)).active()
+    # span 2026-06-05 → 2026-06-13 is 8 days
+    costledger.record(project, "a", rules, today=_dt.date(2026, 6, 5))
+    costledger.record(project, "b", rules, today=_dt.date(2026, 6, 13))
+    led = costledger.load(project)
+    assert costledger.span_days(led) == 8
+    r = costledger.rates(led)
+    assert r["day"] == led["tokens_saved"] / 8
+    assert r["week"] == r["day"] * 7
+    assert r["month"] > r["week"] > r["day"] > 0     # ascending, all positive
+    out = costledger.render_summary(led)
+    for label in ("saved per day", "saved per week", "saved per month", "avg over 8 day(s)"):
+        assert label in out
+
+
+def test_span_floored_to_one_day(project):
+    """A same-day ledger (first == last) yields span 1, not a divide-by-zero."""
+    _seed(project)
+    from fux import loader, config, paths
+    rules = loader.resolve(project, config.load(paths.Footprint(project).config)).active()
+    costledger.record(project, "a", rules, today=_dt.date(2026, 6, 5))
+    led = costledger.load(project)
+    assert costledger.span_days(led) == 1
+    r = costledger.rates(led)
+    assert r["day"] == led["tokens_saved"] and r["week"] == led["tokens_saved"] * 7

{fux_engine-0.3.0 → fux_engine-0.3.2}/tests/test_hookinstall.py

@@ -12,14 +12,16 @@ def _git_init(root):
     subprocess.run(["git", "init", "-q"], cwd=root, check=True)
 
 
-def test_install_wires_all_three_agents(project):
+def test_install_wires_all_three_agents_via_console_script(project):
     out = hookinstall.install(project, ["claude", "codex", "copilot"])
     for agent, rel in settings.AGENT_FILES.items():
         path = project / rel
         assert path.exists(), f"{agent} settings not written"
         hooks = json.loads(path.read_text())["hooks"]
         cmds = [h["command"] for evs in hooks.values() for e in evs for h in e["hooks"]]
-        assert any("fux" in c for c in cmds), f"{agent} has no fux hook"
+        # invokes the installed console script — not a copied wrapper / dev-checkout path.
+        assert "fux context" in cmds, f"{agent} not wired to the fux CLI"
+        assert not any("/.claude/fux/hooks/" in c for c in cmds), f"{agent} points at a copied script"
     assert set(out) == {"claude", "codex", "copilot"}
 
 
@@ -31,14 +33,28 @@ def test_install_is_idempotent(project):
     assert len(hooks["SessionStart"]) == 1
 
 
+def test_rewire_migrates_stale_wrapper_path_to_console_script(project):
+    # Simulate a settings file written by an older Fux that pointed at a copied script.
+    path = project / ".claude/settings.json"
+    stale = {"hooks": {"SessionStart": [{"hooks": [{"type": "command",
+             "command": "/Users/x/.claude/fux/hooks/session_start.sh"}]}]}}
+    path.write_text(json.dumps(stale))
+    settings.wire_file(path)
+    hooks = json.loads(path.read_text())["hooks"]
+    cmds = [h["command"] for e in hooks["SessionStart"] for h in e["hooks"]]
+    assert cmds == ["fux context"]                  # migrated, not duplicated
+    assert not any(".sh" in c for c in cmds)
+
+
 def test_git_install_writes_executable_precommit_shim(project):
     _git_init(project)
     out = hookinstall.install(project, ["git"])
     hook = project / ".git" / "hooks" / "pre-commit"
     assert hook.exists() and hook.stat().st_mode & 0o111, "pre-commit not executable"
     body = hook.read_text()
-    assert "fux-hook" in body                       # our marker
-    assert "pre_commit.sh" in body                  # delegates to the packaged script
+    assert "fux-hook" in body                        # our marker
+    assert "$FUX build" in body and ".fux/out" in body  # self-contained, calls the CLI
+    assert "/.claude/fux/hooks/" not in body         # no copied-script / dev-checkout ref
     assert str(hook) in out["git"]
 
 

fux_engine-0.3.0/fux/data/hooks/pre_commit.sh

@@ -1,27 +0,0 @@
-#!/usr/bin/env bash
-# Fux pre-commit — rebuild the derived views ($0, AST-only) and stage them so
-# .fux/out/ always matches the committed code IN THE SAME COMMIT. Non-blocking:
-# a build failure warns but never aborts the commit (use `fux gate` to *block* on
-# drift). git invokes this with cwd at the repo root. Installed by `fux hooks install`.
-set -uo pipefail
-DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=_common.sh
-. "$DIR/_common.sh"
-
-# Skip during rebase/merge/cherry-pick — don't fight --continue with new changes.
-GIT_DIR="$(git rev-parse --git-dir 2>/dev/null || echo .git)"
-[ -d "$GIT_DIR/rebase-merge" ] && exit 0
-[ -d "$GIT_DIR/rebase-apply" ] && exit 0
-[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
-[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0
-
-# Only act inside a project that has a .fux/ footprint.
-fux_run context >/dev/null 2>&1 || exit 0
-
-echo "[fux hook] rebuilding derived views..."
-if fux_run build >/dev/null 2>&1; then
-  git add .fux/out 2>/dev/null || true   # .session-*.json is gitignored, so skipped
-else
-  echo "[fux hook] build failed — committing without refreshed views (run \`fux build\`)."
-fi
-exit 0