Merge pull request #85 from nikomatsakis/main

update deps, improve docs

Author: nikomatsakis

Cargo.lock

@@ -12,8 +12,11 @@
 
 - [Introduction](./introduction.md)
 - [About](./about.md)
-    - [Rust Crate Sources Tool](./rust-expertise.md)
-    - [Rich Collaboration](./rich-collaboration.md)
+- [How it works](./how-it-works.md)
+- [How to install](./install.md)
+    - [VSCode](./install-vscode.md)
+    - [Other editors](./install-other.md)
+- [How to contribute](./contribute.md)
 
 # Design and implementation
 

md/SUMMARY.md

@@ -1,43 +1,36 @@
-# About Symposium
+# What we want to achieve
 
-Symposium is a set of components that make AI agents work better. These components are compatible with any ACP-based editing system, including Zed, VSCode (with our plugin), and IntelliJ and NeoVim (coming soon).
+You fire up your agent of choice through Symposium. It has a more collaborative style, remembers the way you like to work. It knows about your dependencies and incorporates advice supplied by the crate authors on how best to use them. You can install extensions that transform the agent — new skills, new MCP servers, or more advanced capabilities like custom GUI interfaces and new ways of working.
 
-We focus on three areas:
+## AI the Rust Way
 
-<div class="tenets-grid">
+Symposium brings Rust's design philosophy to AI-assisted development.
 
-<div class="tenet-section">
-  <h2>Rust Expertise</h2>
-  <p>Built-in capabilities for understanding Rust language, errors, and idioms.</p>
-  <ul class="tenet-examples">
-    <li class="works"><a href="./rust-expertise.md">rust-crate-sources tool</a></li>
-    <li class="coming-soon">IDE operations</li>
-    <li class="coming-soon">Error explanations</li>
-  </ul>
-</div>
+<div class="pillars">
 
-<div class="tenet-section">
-  <h2>Ecosystem-Powered Knowledge</h2>
-  <p>Crate authors provide specialized AI tooling through Cargo.toml metadata, bringing domain knowledge directly to the agent.</p>
-  <ul class="tenet-examples">
-    <li class="coming-soon">Crate-provided skills, context, and capabilities</li>
-  </ul>
-</div>
+<div class="pillar">
+<h3>Leverage the wisdom of <s>the crowd</s> crates.io</h3>
+
+Rust embraces a small stdlib and a rich crate ecosystem. Symposium brings that philosophy to AI: your dependencies can teach your agent how to use them. Add a crate, and your agent learns its idioms, patterns, and best practices.
+
+Beyond crate knowledge, we want to make it easy to publish agent extensions that others can try out and adopt just by adding a line to their configuration — the same way you'd add a dependency to `Cargo.toml`.
 
-<div class="tenet-section">
-  <h2>Rich Collaboration</h2>
-  <p>Interactive patterns for human-AI partnership beyond simple text exchanges.</p>
-  <ul class="tenet-examples">
-    <li class="coming-soon"><a href="./rich-collaboration.md">Sparkle collaborative patterns</a></li>
-    <li class="coming-soon">Walkthroughs</li>
-    <li class="coming-soon">Taskspaces</li>
-  </ul>
 </div>
 
+<div class="pillar">
+<h3>Stability without stagnation</h3>
+
+Rust evolves quickly and agents' training data goes stale. Symposium helps your agent take advantage of the latest Rust features and learn how to use new or private crates — things not found in its training data.
+
+We provide guides and context that keep models up-to-date, helping them write idiomatic Rust rather than JavaScript-in-disguise.
+
 </div>
 
-## Open Source Community
+<div class="pillar">
+<h3>Open, portable, and vendor neutral</h3>
 
-Symposium is an open-source project and we are actively soliciting [contributors](./contribute.md). We welcome users as well, but given the exploratory nature of Symposium, expect frequent changes. Currently, the only way to install Symposium is from source.
+Open source tools that everyone can improve. Build extensions once, use them with any ACP-compatible agent. No vendor lock-in.
 
-We maintain a [code of conduct](https://github.com/symposium-dev/symposium/blob/main/CODE_OF_CONDUCT.md) and operate as an independent community focused on exploring what AI has to offer for software development.
+</div>
+
+</div>

md/about.md

@@ -0,0 +1,19 @@
+# How to contribute
+
+Symposium is an open-source project in active development. We're iterating heavily and welcome collaborators who want to shape where this goes.
+
+## Come chat with us
+
+The best way to get involved is to join us on [Zulip](https://symposium.zulipchat.com/). We use it for design discussions, coordination, and general conversation about AI-assisted development.
+
+Drop in, say hello, and tell us what you're interested in working on.
+
+## The codebase
+
+The code lives at [github.com/symposium-dev/symposium](https://github.com/symposium-dev/symposium). 
+
+We maintain a [code of conduct](https://github.com/symposium-dev/symposium/blob/main/CODE_OF_CONDUCT.md) and operate as an independent community exploring what AI has to offer for software development.
+
+## Expectations
+
+Given the exploratory nature of Symposium, expect frequent changes. APIs are unstable, and we're still figuring out the right abstractions. This is a good time to contribute if you want to influence the direction — but be prepared for things to shift as we learn.

md/artwork/logos/rustrover.png

@@ -0,0 +1,30 @@
+# How it works
+
+Symposium is built on [ACP](https://github.com/anthropics/agent-client-protocol)'s proxy architecture. A proxy sits between your editor and your agent, observing and augmenting the conversation. This position lets it do things MCP servers can't:
+
+- Intercept and modify agent behavior
+- Inject context based on your project's dependencies
+- Coordinate multi-step workflows
+- Contribute UI components to the editor
+
+## Current components
+
+### Ferris
+
+[Ferris](https://github.com/symposium-dev/ferris) is an MCP server that gives agents access to Rust-specific patterns and information.
+
+### symposium-cargo
+
+[symposium-cargo](https://github.com/symposium-dev/symposium-cargo) wraps the `cargo` command, capturing build output and providing it to your agent in a structured format. This gives agents better insight into compilation errors, warnings, and test results.
+
+### Sparkle
+
+[Sparkle](https://symposium-dev.github.io/sparkle/) helps agents develop collaborative working patterns. It helps agents remember how you like to work, maintain context across sessions, and engage more naturally in back-and-forth problem solving.
+
+## What we're experimenting with
+
+- **IDE operations**: Bringing language server capabilities (go-to-definition, find references, refactoring) directly to agents
+- **Error explanations**: Rich, context-aware explanations of Rust compiler errors
+- **Crate-provided tooling**: Allowing crate authors to ship agent capabilities alongside their libraries
+- **Walkthroughs**: Interactive guided explorations of code and concepts
+- **Taskspaces**: Isolated working contexts for complex multi-step tasks

md/artwork/logos/vscode.png

@@ -0,0 +1,21 @@
+# Zed, RustRover, Neovim, and other editors
+
+For ACP-compatible editors, install the Symposium agent binary:
+
+```bash
+cargo binstall symposium-acp-agent
+```
+
+Then configure your editor to use `symposium-acp-agent` as the agent command, passing your preferred downstream agent. For example, with Claude Code:
+
+```bash
+symposium-acp-agent -- claude-code --acp
+```
+
+Or with Zed's Claude integration:
+
+```bash
+symposium-acp-agent -- npx -y @anthropic-ai/claude-code-zed
+```
+
+The `--` separates Symposium's arguments from the downstream agent command.

md/artwork/logos/zed.png

@@ -0,0 +1,14 @@
+# VSCode and VSCode-based editors
+
+Install the Symposium extension from:
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=symposium.symposium)
+- [Open VSX Registry](https://open-vsx.org/extension/symposium/symposium)
+
+## Getting started
+
+Once installed, you'll see the Symposium icon in the Activity Bar on the left side of your editor:
+
+<img src="./artwork/ferris-in-a-robe-thick.svg" alt="Symposium icon" width="48"/>
+
+Click the icon to open the Symposium panel. From there you can select your agent and start a chat session.