Skip to content

Commit 63e9fcd

Browse files
ioquatixioquatix
committed
Initial implementation.
0 parents  commit 63e9fcd

File tree

88 files changed

+8172
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

88 files changed

+8172
-0
lines changed

‎.context/agent-context/getting-started.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Getting Started
2+
3+
This guide explains how to use `agent-context`, a tool for discovering and installing contextual information from Ruby gems to help AI agents.
4+
5+
## Overview
6+
7+
`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` directory.
8+
9+
## Installation
10+
11+
Add the gem to your project:
12+
13+
```bash
14+
$ bundle add agent-context
15+
```
16+
17+
Then install agent context files:
18+
19+
```bash
20+
$ bundle exec bake agent:context:install
21+
```
22+
23+
## Commands
24+
25+
```bash
26+
# See what context is available
27+
bake agent:context:list
28+
29+
# Install all available context
30+
bake agent:context:install
31+
32+
# Install context from a specific gem
33+
bake agent:context:install --gem async
34+
35+
# See what context files a gem provides
36+
bake agent:context:list --gem async
37+
38+
# View a specific context file
39+
bake agent:context:show --gem async --file thread-safety
40+
```
41+
42+
## Understanding context/ vs .context/
43+
44+
**Important distinction:**
45+
- **`context/`** (no dot) = Directory in gems that contains context files to share.
46+
- **`.context/`** (with dot) = Directory in your project where context gets installed.
47+
48+
### What happens when you install context?
49+
50+
When you run `bake agent:context:install`, the tool:
51+
52+
1. Scans all installed gems for `context/` directories (in the gem's root).
53+
2. Creates a `.context/` directory in your current project.
54+
3. Copies context files organized by gem name.
55+
56+
For example:
57+
```
58+
your-project/
59+
├── .context/ # ← Installed context (with dot)
60+
│ ├── async/ # ← From the 'async' gem's context/ directory
61+
│ │ ├── thread-safety.md
62+
│ │ └── performance.md
63+
│ └── rack/ # ← From the 'rack' gem's context/ directory
64+
│ └── middleware.md
65+
├── lib/
66+
└── Gemfile
67+
```
68+
69+
Meanwhile, in the gems themselves:
70+
```
71+
async-gem/
72+
├── context/ # ← Source context (no dot)
73+
│ ├── thread-safety.md
74+
│ └── performance.md
75+
├── lib/
76+
└── async.gemspec
77+
```
78+
79+
## Using Context (For Gem Users)
80+
81+
### Why use this?
82+
83+
- **Discover hidden documentation** that gems provide.
84+
- **Get practical examples** and guidance.
85+
- **Understand best practices** from gem authors.
86+
- **Access migration guides** and troubleshooting tips.
87+
88+
### Key Points for Users
89+
90+
- Run `bake agent:context:install` to copy context to `.context/` (with dot).
91+
- The `.context/` directory is where installed context lives in your project.
92+
- Don't edit files in `.context/` - they get completely replaced when you reinstall.
93+
94+
## Providing Context (For Gem Authors)
95+
96+
### How to provide context in your gem
97+
98+
#### 1. Create a `context/` directory
99+
100+
In your gem's root directory, create a `context/` folder (no dot):
101+
102+
```
103+
your-gem/
104+
├── context/ # ← Source context (no dot) - this is what you create
105+
│ ├── getting-started.md
106+
│ ├── configuration.md
107+
│ └── troubleshooting.md
108+
├── lib/
109+
└── your-gem.gemspec
110+
```
111+
112+
**Important:** This is different from `.context/` (with dot) which is where context gets installed in user projects.
113+
114+
#### 2. Add context files
115+
116+
Create files with helpful information for users of your gem. Common types include:
117+
118+
- **getting-started.md** - Quick start guide for using your gem.
119+
- **configuration.md** - Configuration options and examples.
120+
- **troubleshooting.md** - Common issues and solutions.
121+
- **migration.md** - Migration guides between versions.
122+
- **performance.md** - Performance tips and best practices.
123+
- **security.md** - Security considerations.
124+
125+
**Focus on the agent experience:** These files should help AI agents understand how to use your gem effectively, not document your gem's internal APIs.
126+
127+
#### 3. Document your context
128+
129+
Add a section to your gem's README:
130+
131+
```markdown
132+
## Context
133+
134+
This gem provides additional context files that can be installed using `bake agent:context:install`.
135+
136+
Available context files:
137+
- `getting-started.md` - Quick start guide.
138+
- `configuration.md` - Configuration options.
139+
- `troubleshooting.md` - Common issues and solutions.
140+
```
141+
142+
#### 4. File format and content guidelines
143+
144+
Context files can be in any format, but `.md` is commonly used for documentation. The content should be:
145+
146+
- **Practical** - Include real examples and working code.
147+
- **Focused** - One topic per file.
148+
- **Clear** - Easy to understand and follow.
149+
- **Actionable** - Provide specific guidance and next steps.
150+
- **Agent-focused** - Help AI agents understand how to use your gem effectively.
151+
152+
### Key Points for Gem Authors
153+
154+
- Create a `context/` directory (no dot) in your gem's root.
155+
- Put helpful guides for users of your gem there.
156+
- Focus on practical usage, not API documentation.
157+
158+
## Example Context Files
159+
160+
For examples of well-structured context files, see the existing files in this directory:
161+
- `usage.md` - Shows how to use the tool (this file).
162+
- `examples.md` - Demonstrates practical usage scenarios.
163+
164+
## Key Differences from API Documentation
165+
166+
Context files are NOT the same as API documentation:
167+
168+
- **Context files**: Help agents accomplish tasks ("How do I configure authentication?").
169+
- **API documentation**: Document methods and classes ("Method `authenticate` returns Boolean").
170+
171+
Context files should answer questions like:
172+
- "How do I get started?".
173+
- "How do I configure this for production?".
174+
- "What do I do when X goes wrong?".
175+
- "How do I migrate from version Y to Z?".
176+
177+
## Testing Your Context
178+
179+
Before publishing, test your context files:
180+
181+
1. Have an AI agent try to follow your getting-started guide.
182+
2. Check that all code examples actually work.
183+
3. Ensure the files are focused and don't try to cover too much.
184+
4. Verify that they complement rather than duplicate your main documentation.
185+
186+
## Summary
187+
188+
- **`context/`** = source (in gems).
189+
- **`.context/`** = destination (in your project).

‎.context/agent-context/index.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Automatically generated context index for Utopia::Project guides.
2+
# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
3+
---
4+
description: Install and manage context files from Ruby gems.
5+
metadata:
6+
documentation_uri: https://ioquatix.github.io/agent-context/
7+
funding_uri: https://github.com/sponsors/ioquatix/
8+
source_code_uri: https://github.com/ioquatix/agent-context.git
9+
files:
10+
- path: getting-started.md
11+
title: Getting Started
12+
description: This guide explains how to use `agent-context`, a tool for discovering
13+
and installing contextual information from Ruby gems to help AI agents.

‎.context/async-http/getting-started.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Getting Started
2+
3+
This guide explains how to get started with `Async::HTTP`.
4+
5+
## Installation
6+
7+
Add the gem to your project:
8+
9+
~~~ bash
10+
$ bundle add async-http
11+
~~~
12+
13+
## Core Concepts
14+
15+
- {ruby Async::HTTP::Client} is the main class for making HTTP requests.
16+
- {ruby Async::HTTP::Internet} provides a simple interface for making requests to any server "on the internet".
17+
- {ruby Async::HTTP::Server} is the main class for handling HTTP requests.
18+
- {ruby Async::HTTP::Endpoint} can parse HTTP URLs in order to create a client or server.
19+
- [`protocol-http`](https://github.com/socketry/protocol-http) provides the abstract HTTP protocol interfaces.
20+
21+
## Usage
22+
23+
### Making a Request
24+
25+
To make a request, use {ruby Async::HTTP::Internet} and call the appropriate method:
26+
27+
~~~ ruby
28+
require 'async/http/internet/instance'
29+
30+
Sync do
31+
Async::HTTP::Internet.get("https://httpbin.org/get") do |response|
32+
puts response.read
33+
end
34+
end
35+
~~~
36+
37+
The following methods are supported:
38+
39+
~~~ ruby
40+
Async::HTTP::Internet.methods(false)
41+
# => [:patch, :options, :connect, :post, :get, :delete, :head, :trace, :put]
42+
~~~
43+
44+
Using a block will automatically close the response when the block completes. If you want to keep the response open, you can manage it manually:
45+
46+
~~~ ruby
47+
require 'async/http/internet/instance'
48+
49+
Sync do
50+
response = Async::HTTP::Internet.get("https://httpbin.org/get")
51+
puts response.read
52+
ensure
53+
response&.close
54+
end
55+
~~~
56+
57+
As responses are streamed, you must ensure it is closed when you are finished with it.
58+
59+
#### Persistence
60+
61+
By default, {ruby Async::HTTP::Internet} will create a {ruby Async::HTTP::Client} for each remote host you communicate with, and will keep those connections open for as long as possible. This is useful for reducing the latency of subsequent requests to the same host. When you exit the event loop, the connections will be closed automatically.
62+
63+
### Downloading a File
64+
65+
~~~ ruby
66+
require 'async/http/internet/instance'
67+
68+
Sync do
69+
# Issue a GET request to Google:
70+
response = Async::HTTP::Internet.get("https://www.google.com/search?q=kittens")
71+
72+
# Save the response body to a local file:
73+
response.save("/tmp/search.html")
74+
ensure
75+
response&.close
76+
end
77+
~~~
78+
79+
### Posting Data
80+
81+
To post data, use the `post` method:
82+
83+
~~~ ruby
84+
require 'async/http/internet/instance'
85+
86+
data = {'life' => 42}
87+
88+
Sync do
89+
# Prepare the request:
90+
headers = [['accept', 'application/json']]
91+
body = JSON.dump(data)
92+
93+
# Issues a POST request:
94+
response = Async::HTTP::Internet.post("https://httpbin.org/anything", headers, body)
95+
96+
# Save the response body to a local file:
97+
pp JSON.parse(response.read)
98+
ensure
99+
response&.close
100+
end
101+
~~~
102+
103+
For more complex scenarios, including HTTP APIs, consider using [async-rest](https://github.com/socketry/async-rest) instead.
104+
105+
### Timeouts
106+
107+
To set a timeout for a request, use the `Task#with_timeout` method:
108+
109+
~~~ ruby
110+
require 'async/http/internet/instance'
111+
112+
Sync do |task|
113+
# Request will timeout after 2 seconds
114+
task.with_timeout(2) do
115+
response = Async::HTTP::Internet.get "https://httpbin.org/delay/10"
116+
ensure
117+
response&.close
118+
end
119+
rescue Async::TimeoutError
120+
puts "The request timed out"
121+
end
122+
~~~
123+
124+
### Making a Server
125+
126+
To create a server, use an instance of {ruby Async::HTTP::Server}:
127+
128+
~~~ ruby
129+
require 'async/http'
130+
131+
endpoint = Async::HTTP::Endpoint.parse('http://localhost:9292')
132+
133+
Sync do |task|
134+
Async(transient: true) do
135+
server = Async::HTTP::Server.for(endpoint) do |request|
136+
::Protocol::HTTP::Response[200, {}, ["Hello World"]]
137+
end
138+
139+
server.run
140+
end
141+
142+
client = Async::HTTP::Client.new(endpoint)
143+
response = client.get("/")
144+
puts response.read
145+
ensure
146+
response&.close
147+
end
148+
~~~

‎.context/async-http/index.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Automatically generated context index for Utopia::Project guides.
2+
# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
3+
---
4+
description: A HTTP client and server library.
5+
metadata:
6+
documentation_uri: https://socketry.github.io/async-http/
7+
source_code_uri: https://github.com/socketry/async-http.git
8+
files:
9+
- path: getting-started.md
10+
title: Getting Started
11+
description: This guide explains how to get started with `Async::HTTP`.
12+
- path: testing.md
13+
title: Testing
14+
description: This guide explains how to use `Async::HTTP` clients and servers in
15+
your tests.

0 commit comments

Comments
 (0)