phase 1 done

1 files changed, 114 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..de4c962
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+# pantograph: a minimal coding agent
+
+```
+                                  ?+                                           
+                                 `?]                                           
+                                 ]?~                                           
+                                [??                                            
+                               [??                                             
+                              ,?]"                                             
+ '.                           ??-                                              
+ 1111}}}}}}!''               ???                                               
+        |(([[[[\[u]]f]]'`   {??                                                
+                   1((?]][[)tz)[]?'                                            
+                           ]Q?/|)?????v??-??_.                                 
+                          ]Ur            )))?]?????n??[)Y'_                    
+                         ?]|:                       `\t-??:                    
+                         ]]]                           ---                     
+                        ]]]                           ]?-^                     
+                       ]]].                           -?-                      
+                      ']]+                           ~]-`                      
+                      [\]                            --?                       
+                     [x]                            "]?`                       
+                    {]]I                            ???                        
+                    []?                            '??l                        
+                   )Y})}}[+                        ?-?                         
+                    \l//[]???-j]u??-              .?-?                         
+                    ^         l\\--??]??]]??_.    ???                          
+                                       i|\---?]]}t>.?~                         
+                                                )??]}]]]]f?C?],                
+                                                I???    `f11]?]]}]n][?[        
+                                                ?fc              ^)1]??]?]Y]}} 
+                                               ^???                       '{{] 
+                                               ??Y                             
+                                              ^]??                             
+                                              ]]].                             
+                                             ^]]]                              
+                                             ]~x'                              
+                                            `]J\                               
+                                            [}[`                               
+                                           `[X[                                
+                                           }}[`                                
+                                          .}}[                                 
+                                          /p]`                                 
+                                         '1t}                                  
+```
+
+A pantograph is a draftsman's instrument: a jointed parallelogram of four
+rods, pinned at one end to a fixed pivot. The draftsman moves a stylus over
+the original drawing; a pen at the far end of the linkage traces the same
+path, scaled. Small movements at the stylus become larger movements at the
+pen, in exact proportion, without the draftsman ever having to think about
+the ratio. The geometry does the work.
+
+What the tool offers is *controlled leverage*. The operator stays close to
+the source — eyes on the original, hand on the stylus — and the mechanism
+reproduces that intent at a different scale, faithfully, without slop. The
+linkage doesn't make decisions; it amplifies the ones you make.
+
+That is the goal for `pantograph`: a coding agent built as a precise
+linkage between operator and model. Your attention stays on the work; the
+tool turns small, deliberate movements into larger ones, in proportion, and
+adds nothing of its own.
+
+## The shape of it
+
+- **Core in Zig.** One binary, small footprint, fast startup. The agent
+  loop and nothing else.
+- **`libpanto`.** The same loop behind a C ABI, so other programs can
+  embed it instead of shelling out.
+- **Two provider shapes.** Anthropic-shaped and OpenAI-shaped APIs at
+  arbitrary base URLs. Both work all the way through, or they aren't
+  shipped.
+- **Server mode.** Run as a daemon that speaks those same two API shapes
+  itself, routing to its configured backends. A small, durable provider
+  router; the useful slice of something like `omniroute`, without the
+  memory cost or the fragile bits.
+
+## What is not in the core
+
+A coding agent accumulates features the way a train roof accumulates
+ironwork. `pantograph` resists that. The following are deliberately *not*
+built in:
+
+- subagents
+- MCP
+- permission systems
+- AGENTS.md automation
+- skills
+- customizable `/prompts`
+- the basic tools — `read`, `write`, `edit`, `bash` — even these ship as
+  extensions and can be disabled individually
+
+Each of these is a reasonable thing to want. None of them needs to live in
+the core.
+
+## Extensions
+
+Extensions are how everything above gets back into the picture, on terms
+that don't compromise the rest of the machine.
+
+- **Lua first.** Cheap to embed, quick to iterate in, easy to sandbox.
+- **Native next.** A C ABI for shared-object extensions, so anything that
+  can produce a `.so` — Zig, Rust, C, C++ — can plug in.
+- **Crash isolation as a first-class concern.** A bad extension should
+  not take the host down with it. The standard tools will themselves be
+  ported to native extensions once that path is solid.
+
+Extensions are how `pantograph` stays small without becoming useless.
+
+## Status
+
+Early. The thinking lives in `ideas.md`; the staged plan lives in
+`docs/phase-1.md` through `docs/phase-4.md`. Source is under `src/` for
+the CLI and `libpanto/` for the embeddable library.