@niroai/niro 0.16.0 → 0.18.0

package/docs/supported-swift.md

@@ -0,0 +1,133 @@
+# Supported in Swift
+
+<!-- GENERATED by scripts/gen-supported-docs.js. Do not edit by hand: run the script again. -->
+<!-- source: catalog/swift.json; catalog/swift.structure.json -->
+<!-- measured: coverage corpus 1bb4ebb, niro-local 2b30d4fd -->
+
+This page lists the Swift libraries, frameworks and build tools Niro was tested against, and whether it recognised each one.
+
+**What the marks mean.**
+
+- **Supported:** Niro recognised every way of using it that the test code tries.
+- **Partly:** Niro recognised some of those ways, or recognised one only in part.
+- **Not yet:** Niro did not recognise it in the test code.
+
+The test code is made up for the purpose: one small service per library, with the names invented. So "supported" means Niro recognised it there. It is good evidence, but it is not a promise about every codebase. If Niro misses something in your code, the coverage audit reports the gap on its own (see [coverage-audit-and-consent.md](coverage-audit-and-consent.md)).
+<!-- source: niro-coverage-corpus README.md ("Synthetic test code ... All names are made up"); catalog status merged pairs one to one with measured found -->
+
+The test catalog also holds 5 look-alike cases for Swift: code that Niro must NOT take for a route, a call or a store. They test that Niro ignores the look-alike, so they are left out of this page and its counts.
+<!-- source: catalog/swift.json and catalog/swift.structure.json, rows marked as traps (scripts/gen-supported-docs.js isTrap) -->
+
+## Web frameworks and HTTP servers (the routes your code serves)
+
+1 supported, 1 partly, 4 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| Hummingbird | partly | yes: let router = Router(); router.get("path") { request, context in }<br>yes: router.post("path", use: handler)<br>yes: router.group("api").get("x/:id") { .. }<br>no: RouteCollection(context:).get(":id", use:) added with router.addRoutes(_:atPath:) |
+| Kitura | not yet | no: router.get("/path") { request, response, next in } |
+| Perfect | not yet | no: routes.add(method: .get, uri: "/path") { request, response in } |
+| Swifter | not yet | no: server["/path"] = { request in } and server.GET["/path"] = { }<br>no: server.POST["/path"] = { } |
+| SwiftNIO | not yet | no: ChannelInboundHandler with switch (head.method, head.uri) cases |
+| Vapor | supported | yes: app.get("path") { req in ... } with a trailing closure<br>yes: app.post("path", use: handler) and path segments as separate arguments<br>yes: app.on(.PATCH, "path", use: handler)<br>yes: let api = app.grouped("api", "v1"); api.get(..)<br>yes: app.group("admin") { admin in admin.post(..) }<br>yes: struct X: RouteCollection { func boot(routes:) { routes.grouped("x").get(use: h) } } registered with app.register(collection:)<br>yes: invoices.group(":id") { invoice in invoice.delete(use: delete) } inside boot(routes:) |
+
+## The language's own HTTP server
+
+0 supported, 0 partly, 1 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| Network.framework NWListener | not yet | no: NWListener(using: .tcp, on: port) with newConnectionHandler reading the request line |
+
+## HTTP client libraries (the calls your code makes to other services)
+
+1 supported, 2 partly, 2 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| Alamofire | partly | yes: AF.request("url").response { }<br>yes: AF.request(url, method: .post, parameters:, encoder:)<br>no: let session = Session(configuration:); session.request(url)<br>partly: AF.upload(data, to: url)<br>yes: AF.download(url)<br>yes: try await AF.request(url).serializingString().value |
+| AsyncHTTPClient | partly | partly: var r = HTTPClientRequest(url:); r.method = .POST; HTTPClient.shared.execute(r, timeout:)<br>yes: HTTPClient(eventLoopGroupProvider:).get(url:).wait() |
+| Moya | not yet | no: enum API: TargetType with baseURL, path and method in switch branches; MoyaProvider<API>().request(.case) |
+| swift-openapi-generator | not yet | no: Client(serverURL:transport: URLSessionTransport()) then client.<operationId>() from openapi.yaml |
+| Vapor | supported | yes: Vapor's client: req.client.get("absolute url")<br>yes: req.client.post(URI(string: url)) { try $0.content.encode(..) } |
+
+## The language's own HTTP client
+
+0 supported, 1 partly, 1 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| Network.framework NWConnection | not yet | no: NWConnection(host:port:using: .tcp) then send(content: "GET /path HTTP/1.1...") |
+| URLSession | partly | yes: URLSession.shared.dataTask(with: URL(string:)!) { } .resume()<br>yes: try await URLSession.shared.data(from: URL)<br>yes: var request = URLRequest(url:); request.httpMethod = "POST"; request.httpBody = ..; data(for: request)<br>yes: try await URLSession.shared.upload(for: request, from: data)<br>yes: URLSession.shared.uploadTask(with: request, from: data) { }.resume()<br>yes: try await URLSession.shared.download(from: URL)<br>yes: URLSession.shared.downloadTask(with: URL) { }.resume()<br>yes: try await URLSession.shared.bytes(from: URL)<br>yes: let session = URLSession(configuration: .ephemeral); session.data(from:)<br>partly: base URL from ProcessInfo environment with a literal fallback, joined with +<br>partly: client class holding session and baseURL; baseURL.appendingPathComponent(path); path given by the caller |
+
+## gRPC
+
+1 supported, 1 partly, 1 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| connect-swift | not yet | no: Connect: ProtocolClient(httpClient:config:) and generated <Pkg>_<S>Client(client:).<rpc>(request:) |
+| grpc-swift | partly | yes: server v1, form implements: class X: <Pkg>_<S>Provider with func <rpc>(request:context:) -> EventLoopFuture<br>yes: registration: Server.insecure(group:).withServiceProviders([X()]).bind(host:port:)<br>yes: server v1 async, form implements: class X: <Pkg>_<S>AsyncProvider with async throws methods<br>no: client v1, form constructor: <Pkg>_<S>NIOClient(channel:) then client.<rpc>(req).response<br>no: client v1, form constructor: <Pkg>_<S>AsyncClient(channel:) then try await client.<rpc>(req) |
+| grpc-swift-2 | supported | yes: server v2, form implements: struct X: <Pkg>_<S>.SimpleServiceProtocol; GRPCServer(transport:services:)<br>yes: client v2, form constructor: <Pkg>_<S>.Client(wrapping: grpcClient) inside withGRPCClient |
+
+## Databases and data stores
+
+3 supported, 3 partly, 7 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| CloudKit | supported | yes: CKRecord(recordType: "X") saved with database.save; CKQuery(recordType:) |
+| Core Data | not yet | no: NSFetchRequest<T>(entityName: "X") then context.fetch(request)<br>no: Order.fetchRequest() from a NSManagedObject subclass, then context.fetch<br>no: NSEntityDescription.insertNewObject(forEntityName: "X", into: context); context.save()<br>no: context.execute(NSBatchDeleteRequest(fetchRequest: NSFetchRequest(entityName:))) |
+| FileManager | supported | yes: FileManager.default.createFile(atPath:contents:attributes:) / contents(atPath:) |
+| Firebase Firestore | not yet | no: db.collection("x").document(id).setData(..) / .getDocuments()<br>no: db.collection("x").addDocument(data:) |
+| Fluent | not yet | no: Model.query(on: db).filter(..).all() with static let schema = "table"<br>no: model.save(on: db)<br>no: (db as? SQLDatabase).raw("SQL").run() |
+| GRDB | not yet | no: db.execute(sql:arguments:) inside dbQueue.write { db in }<br>no: Row.fetchAll(db, sql:)<br>no: record type with databaseTableName; Invoice.fetchAll(db), invoice.insert(db) |
+| MongoKitten | not yet | no: db["collection"].insert(..) / .find(..) |
+| PostgresNIO | partly | yes: PostgresClient.query("SQL with \(interpolation)", logger:)<br>partly: client.withConnection { connection in connection.query(..) }<br>yes: shared table: main writes shipments that services/fluent reads |
+| RealmSwift | partly | yes: realm.objects(Type.self)<br>partly: try realm.write { realm.add(instance) } |
+| RediStack | not yet | no: redis.set("key", to: v) / redis.get("key", as:) |
+| SQLite.swift | supported | yes: let carts = Table("carts"); db.run(carts.insert(..)); db.prepare(carts)<br>yes: db.execute("raw SQL") |
+| SwiftData | not yet | no: context.fetch(FetchDescriptor<Model>(predicate:)) on a @Model class<br>no: modelContext.insert(Model(..))<br>no: SwiftUI @Query var items: [Model] |
+| UserDefaults | partly | yes: UserDefaults.standard.set(v, forKey: "k") / .string(forKey:)<br>no: UserDefaults(suiteName: "group.x")?.set(v, forKey:)<br>no: SwiftUI property wrapper @AppStorage("key") |
+
+## Messaging and events (queues, topics, streams)
+
+6 supported, 1 partly, 4 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| CocoaMQTT | supported | yes: mqtt.publish("topic", withString:)<br>yes: mqtt.subscribe("topic", qos:) with didReceiveMessage<br>yes: shared MQTT topic: main publishes warehouse/temperature |
+| Combine | supported | yes: in-process: subject.send(value) on a PassthroughSubject<br>yes: in-process: CurrentValueSubject.send(value) |
+| DistributedNotificationCenter | not yet | no: macOS cross-process: DistributedNotificationCenter.default().postNotificationName(..) / addObserver(forName:) |
+| nats.swift | supported | yes: nats.subscribe(subject:) / nats.publish(data, subject:)<br>yes: shared NATS subject: main publishes shipments.created |
+| NotificationCenter | supported | yes: NotificationCenter.default.post(name: Notification.Name("X"), object:)<br>yes: post(name: .orderPlaced) where .orderPlaced is declared in an extension of Notification.Name<br>yes: addObserver(forName:object:queue:) { note in }<br>yes: addObserver(self, selector: #selector(f), name: Notification.Name("X"), object:)<br>yes: NotificationCenter.default.publisher(for: name).sink { }<br>yes: for await _ in NotificationCenter.default.notifications(named:) |
+| rabbitmq-nio | supported | yes: channel.basicPublish(from:exchange:routingKey:) / basicConsume(queue:) |
+| RediStack | supported | yes: redis.publish(message, to: "channel")<br>yes: redis.subscribe(to: "channel") { channel, message in }<br>yes: shared Redis channel: main publishes stock-updates |
+| Soto (AWS SNS) | not yet | no: sns.publish(.init(message:topicArn:)) |
+| Soto (AWS SQS) | not yet | no: sqs.sendMessage(.init(messageBody:queueUrl:))<br>no: sqs.receiveMessage(.init(queueUrl:))<br>no: shared SQS queue URL: main sends to refunds |
+| swift-kafka-client | partly | no: producer.send(KafkaProducerMessage(topic: "t", value:))<br>no: KafkaConsumerConfiguration(consumptionStrategy: .group(id:topics: ["t"])); for try await m in consumer.messages<br>partly: shared topic: main produces orders.placed that services/swift-kafka consumes |
+| Vapor Queues | not yet | no: req.queue.dispatch(Job.self, payload); struct Job: AsyncJob { func dequeue } |
+
+## Build tools and package managers
+
+8 supported, 0 partly, 0 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| Bazel rules_swift | supported | yes: MODULE.bazel + BUILD.bazel with swift_binary and swift_library, no Package.swift |
+| Carthage | supported | yes: Cartfile; Carthage/Checkouts (sources) and Carthage/Build (frameworks) beside an Xcode project |
+| CocoaPods | supported | yes: Podfile with a remote pod (vendored under Pods/) and a development pod by :path with a .podspec |
+| SwiftPM | supported | yes: one Package.swift: executableTarget with main.swift, a library target, a testTarget<br>yes: products: .executable and .library; @main type instead of main.swift<br>yes: two app packages depend on a local library package by .package(path:)<br>yes: a .macro target (swift-syntax) and a build-tool .plugin under Plugins/, used by an executable |
+| Tuist | supported | yes: Workspace.swift and Project.swift manifests (Swift code importing ProjectDescription) per project |
+| Xcode project | supported | yes: ShopApp.xcodeproj with an app target, a framework folder and a unit-test folder; no Package.swift |
+| Xcode workspace | supported | yes: Shop.xcworkspace referencing two .xcodeproj (app and framework) |
+| XcodeGen | supported | yes: project.yml declaring an application target and a framework target by source folder |
+
+## Project and folder layouts
+
+1 supported, 1 partly, 0 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| SwiftPM | supported | yes: targets with path: outside Sources/ (Server/Sources, Shared/Lib, Server/Tests)<br>yes: .build/ (checkouts and debug output), .swiftpm/ and DerivedData/ beside Package.swift, no .gitignore<br>yes: several SwiftPM services under services/<name>/ (code in Sources/, not src/), split by a root docker-compose.yml |
+| Xcode project | partly | partly: one app target mixing Swift and Objective-C through a bridging header |

package/docs/supported-typescript.md

@@ -0,0 +1,220 @@
+# Supported in TypeScript
+
+<!-- GENERATED by scripts/gen-supported-docs.js. Do not edit by hand: run the script again. -->
+<!-- source: catalog/typescript.json; catalog/typescript.structure.json -->
+<!-- measured: coverage corpus 1bb4ebb, niro-local 2b30d4fd -->
+
+This page lists the TypeScript libraries, frameworks and build tools Niro was tested against, and whether it recognised each one.
+
+**What the marks mean.**
+
+- **Supported:** Niro recognised every way of using it that the test code tries.
+- **Partly:** Niro recognised some of those ways, or recognised one only in part.
+- **Not yet:** Niro did not recognise it in the test code.
+
+The test code is made up for the purpose: one small service per library, with the names invented. So "supported" means Niro recognised it there. It is good evidence, but it is not a promise about every codebase. If Niro misses something in your code, the coverage audit reports the gap on its own (see [coverage-audit-and-consent.md](coverage-audit-and-consent.md)).
+<!-- source: niro-coverage-corpus README.md ("Synthetic test code ... All names are made up"); catalog status merged pairs one to one with measured found -->
+
+The test catalog also holds 19 look-alike cases for TypeScript: code that Niro must NOT take for a route, a call or a store. They test that Niro ignores the look-alike, so they are left out of this page and its counts.
+<!-- source: catalog/typescript.json and catalog/typescript.structure.json, rows marked as traps (scripts/gen-supported-docs.js isTrap) -->
+
+## Web frameworks and HTTP servers (the routes your code serves)
+
+45 supported, 3 partly, 4 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| @adonisjs/core | partly | yes: router.get(path, handler) in start/routes.ts<br>no: router.resource('podcasts', Controller).only([...])<br>yes: router.group(() => {...}).prefix('/admin') |
+| @analogjs/platform | supported | yes: src/server/routes/api/<path>.<verb>.ts: Analog API routes (Nitro), verb from the file name<br>yes: src/server/routes/api/<path>/[param].ts: a dynamic Analog API route, every verb |
+| @angular/router | supported | yes: Routes array { path: 'quotes/:id', component }: client-side routes, NOT endpoints |
+| @azure/functions (v3 programming model) | supported | yes: <FunctionName>/function.json with an httpTrigger binding: route (with {param}, {param:constraint}, {param?}) and methods, under host.json routePrefix (default api)<br>yes: function.json httpTrigger with no route: /api/<FunctionName>, the folder name |
+| @azure/functions (v4) | supported | yes: app.http('name', { methods, route, handler }); served under /api<br>yes: app.get / app.post / app.put / app.patch / app.deleteRequest(name, handler or options): the verb is the call, the route is options.route or the name |
+| @builder.io/qwik-city | supported | yes: src/routes/<path>/index.ts exporting onGet, onPost, ...: a Qwik City endpoint (only index files are routes)<br>yes: src/routes/<path>/[param]/index.ts: a dynamic Qwik City endpoint<br>yes: index.ts exporting onRequest: one handler for every method, here under a [...rest] folder<br>yes: src/routes/(group)/<path>/index.ts: a grouped folder is left out of the URL |
+| @fastify/autoload | supported | yes: register(AutoLoad, { dir: 'routes' }): each folder's name prefixes the routes its plugin registers (dirNameRoutePrefix default true)<br>yes: routeParams: true: a folder named _param becomes :param in the prefix<br>yes: options: { prefix } on the AutoLoad registration, plus export const autoPrefix in the plugin file |
+| @loopback/rest | not yet | no: lower-case @get('/x/{id}') and @post('/x') on methods |
+| @nestjs/common | partly | yes: @Controller('prefix') class with @Get(), @Get(':id'), @Post()<br>yes: @Put(path), @Patch(path), @Delete(path) with stacked decorators<br>partly: app.setGlobalPrefix('api') in main.ts applies to every controller<br>partly: @Controller({ path, version }) with URI versioning |
+| @oak/oak (Deno) | supported | yes: new Router().get().post() imported from jsr:@oak/oak |
+| @react-router/dev (React Router v7 framework mode) | supported | yes: app/routes.ts config: route('api/stock/:sku', './api/stock.ts') and prefix('v2', [...]) name the path and the module |
+| @react-router/fs-routes (React Router v7 framework mode) | supported | yes: app/routes.ts `export default flatRoutes()` and app/routes/<dotted>.ts resource routes (loader GET, action POST/PUT/PATCH/DELETE) |
+| @remix-run/node | supported | yes: app/routes/<dotted.path>.tsx exporting loader (GET) and action (POST) |
+| @remix-run/node (Remix v2) | supported | yes: a resource route: a route module with a loader and no default component, serving GET only<br>yes: <parent>._index.ts: the index route of a parent path<br>yes: <path>.$.ts: a splat route, params['*'] holds the rest of the URL<br>yes: _layout.<path>.ts: a leading underscore segment is a pathless layout, left out of the URL<br>yes: <segment>_.<rest>.ts: a trailing underscore opts out of the parent layout; the underscore is not in the URL<br>yes: ($param).<path>.ts: an optional segment, matching with and without it<br>yes: [.] or [.ext] in a file name keeps a literal dot in the URL<br>yes: <path>/route.ts: a folder route; other modules in the folder are not routes |
+| @solidjs/start | supported | yes: src/routes/<path>.ts exporting GET, POST, ... (no default component): a SolidStart API route<br>yes: src/routes/<path>/[param].ts: a dynamic SolidStart API route<br>yes: src/routes/<path>/[...rest].ts: a catch-all SolidStart API route, verb bound by `export const GET = handler`<br>yes: src/routes/(group)/<path>/[[optional]].ts: a group folder and an optional parameter; one function bound to two verbs |
+| @sveltejs/kit | supported | yes: src/routes/<path>/+server.ts exporting GET/POST/DELETE (const or function)<br>yes: src/routes/<path>/[param]/+server.ts: a dynamic segment<br>yes: src/routes/<path>/[...rest]/+server.ts: a rest parameter, which may match zero segments<br>yes: src/routes/<path>/[[optional]]/...: an optional parameter in the middle of the path<br>yes: src/routes/(group)/<path>/+server.ts: a group folder is left out of the URL<br>yes: src/routes/<path>/[id=matcher]/+server.ts: a parameter with a matcher from src/params<br>yes: +server.ts exporting `fallback`: serves every method with no handler of its own<br>yes: +page.server.ts `export const actions`: form actions answer POST at the page's path (default) or ?/name<br>yes: +server.ts beside +page.svelte in one folder (content negotiation): GET with Accept text/html goes to the page, others to +server |
+| @tanstack/react-start | supported | yes: src/routes/<path>.ts: createFileRoute('/path')({ server: { handlers: { GET, POST } } }); a file may also hold a component<br>yes: src/routes/<path>/$param.ts, $.ts splat and [.] escape in a server route |
+| @tanstack/start (before the Vite move) | supported | yes: app/routes/api/<path>.ts: export const APIRoute = createAPIFileRoute('/api/path')({ GET, POST }) |
+| @trpc/server | not yet | no: t.router({ ns: t.router({ q: procedure.query(), m: procedure.mutation() }) }): GET /trpc/ns.q, POST /trpc/ns.m |
+| astro | supported | yes: src/pages/<path>.ts exporting GET/POST APIRoute<br>yes: src/pages/<path>/[param].ts in server output: a dynamic endpoint; _file and _folder are excluded<br>yes: src/pages/<path>/[...path].ts: a rest parameter, which also matches the bare path<br>yes: src/pages/<name>.<ext>.ts: the output extension stays in the URL (feed.json.ts -> /feed.json), also after a parameter |
+| AWS SAM template.yaml | supported | yes: Events: Type: HttpApi Properties: Path, Method; Handler names the export |
+| aws-lambda (API Gateway v2) | not yet | no: switch (event.routeKey) { case 'GET /claims': ... } |
+| bun (Bun.FileSystemRouter) | supported | yes: new Bun.FileSystemRouter({ style: 'nextjs', dir }) with router.match(req) in Bun.serve: Next.js-style file names under dir, no method chosen |
+| Cloudflare Pages Functions | supported | yes: functions/<path>.ts exporting onRequest: every verb at the file's path<br>yes: exports onRequestGet, onRequestPost, onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions: the export name is the verb<br>yes: functions/index.ts serves / and functions/<dir>/index.ts serves /<dir><br>yes: functions/<dir>/[param].ts: one segment, value in context.params<br>yes: functions/<dir>/[[param]].ts: matches any depth, params.param is an array<br>yes: _routes.json in the build output folder: exclude wins over include, an excluded path never reaches a function |
+| elysia | partly | yes: new Elysia().get().post() chained<br>no: app.group('/prefix', app => app.get(...)) |
+| elysia-autoload | supported | yes: app.use(await autoload({ dir, prefix })): routes/<path>.ts default-exports (app) => app.get('', ...); [id].ts and [...].ts |
+| Expo Router API routes (expo-router) | supported | yes: app/<path>+api.ts exporting GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS with web Request and Response<br>yes: app/<dir>/[param]+api.ts: one segment, passed as the second argument<br>yes: a (group) folder adds nothing to the URL<br>yes: app/<dir>/[...rest]+api.ts: catch-all |
+| express | supported | yes: typed Router (Request<Params>, Response) mounted with app.use("/api", router) |
+| express-file-routing | supported | yes: routes/<path>.ts exporting get, post, put, patch, del; mounted with app.use('/api', await router())<br>yes: a default export serves every method; [...path].ts is a catch-all (not the base path alone) |
+| fastify | supported | yes: Fastify().withTypeProvider<T>().get(path, { schema }, h); fastify.post<{ Body }>(path, h) |
+| fresh (deno.land/x/fresh, Fresh 1) | supported | yes: routes/<path>.ts: export const handler: Handlers = { GET, POST } |
+| fresh (jsr:@fresh/core, Fresh 2) | supported | yes: routes/<path>.ts: export const handler = define.handlers({ GET, POST, ... })<br>yes: define.handlers((ctx) => ...): one function serves every method<br>yes: [...path] catch-all, [[optional]] parameter and (group) folder in Fresh routes |
+| Gatsby Functions (gatsby) | supported | yes: src/api/<path>.ts default export handler(req, res): /api/<path>, every verb<br>yes: src/api/<dir>/index.ts: /api/<dir><br>yes: src/api/<dir>/[param].ts: one segment, value in req.params<br>yes: src/api/<dir>/[...].ts (or [...name].ts): matches everything after the splat |
+| h3 | supported | yes: createRouter().get(path, defineEventHandler(...)) |
+| hono | supported | yes: app.get/app.post(path, handler)<br>yes: app.route('/prefix', subApp)<br>yes: new Hono().basePath('/api').get(path) |
+| honox | supported | yes: app/routes/<path>.ts: export default createRoute(...) serves GET<br>yes: app/routes/<path>.ts: export const POST = createRoute(...) and the other verbs |
+| inversify-express-utils | not yet | no: @controller('/x') with @httpGet, @httpPost, @httpDelete |
+| Netlify Edge Functions (@netlify/edge-functions) | supported | yes: netlify/edge-functions/<name>.ts default export with export const config = { path } |
+| Netlify Functions (@netlify/functions) | supported | yes: netlify/functions/<name>.mts default export (req, context) with no config.path: /.netlify/functions/<name><br>yes: export const config: Config = { path: '/x/:id', method: [...] }: the path replaces /.netlify/functions/<name><br>yes: config.path as an array, with * wildcards and :named groups<br>yes: netlify/functions/<name>/index.mts or <name>/<name>.mts is function <name>; other files in the folder are helpers |
+| Netlify Functions (@netlify/functions), Lambda-compatible | supported | yes: netlify/functions/<name>.ts exporting handler(event, context): served at /.netlify/functions/<name>, every verb |
+| netlify.toml | supported | yes: [functions] directory = '<dir>': functions are read from that folder instead of netlify/functions<br>yes: [[redirects]] from = '/x/*' to = '/.netlify/functions/<name>' status = 200: a rewrite to a function<br>yes: [[edge_functions]] path = '/x/*' function = '<name>': routes an edge function from config |
+| next | supported | yes: app/<path>/[[...slug]]/route.ts: optional catch-all segment, also matches the bare folder path<br>yes: app/<path>/[...slug]/route.ts: catch-all segment in the app router<br>yes: app/(group)/<path>/route.ts: a route group folder is left out of the URL<br>yes: app/<path>/_folder/...: a private folder opts out of routing; %5Ffolder is the escape that keeps a literal underscore<br>yes: a route.ts handler in a child segment of a page, outside app/api; page.tsx, layout.tsx and proxy.ts are not endpoints<br>yes: route.ts with `export const runtime = 'edge'`: an edge route handler<br>yes: a folder whose name holds a dot, app/rss.xml/route.ts, serves /rss.xml<br>yes: metadata route files app/sitemap.ts and app/robots.ts are special route handlers serving /sitemap.xml and /robots.txt<br>yes: src/app/<path>/route.ts: the app router placed under src/<br>yes: src/pages/api/<name>.ts: the pages router API placed under src/<br>yes: pages/api/<path>/[...slug].ts: catch-all API route, as NextAuth's pages/api/auth/[...nextauth].ts<br>yes: pages/api/<path>/[[...slug]].ts: optional catch-all API route, also matches the bare path<br>yes: app/ at the root and src/app both present: src/app is ignored |
+| next (app router) | supported | yes: app/api/<path>/route.ts exporting GET/POST functions<br>yes: app/api/products/[id]/route.ts dynamic segment |
+| next (pages router) | supported | yes: pages/api/<name>.ts typed NextApiRequest handler |
+| nitropack (standalone Nitro) | supported | yes: a standalone Nitro app: routes/<path>.ts under srcDir (server/ here), verb from the file name<br>yes: a standalone Nitro app: api/<path>.ts served under /api |
+| nuxt (nitro) | supported | yes: server/api/<name>.<verb>.ts default defineEventHandler: path and verb from the file name<br>yes: server/routes/<name>.ts: any verb, no /api prefix<br>yes: server/api/<path>/[id].get.ts: a dynamic segment with a verb in the file name; also two parameters in two folders<br>yes: server/api/<path>/index.post.ts: an index file with a verb serves the folder's own path<br>yes: server/api/<path>/[...slug].ts: a named catch-all, which also matches the base path<br>yes: server/api/<path>/[...].ts: an unnamed catch-all (params._) |
+| RedwoodJS functions (@redwoodjs/api) | supported | yes: api/src/functions/<name>.ts exporting handler(event, context): served at /<name><br>yes: api/src/functions/<name>/<name>.ts or <name>/index.ts: function <name>; other files there are not exposed |
+| routing-controllers | supported | yes: @JsonController('/x') with @Get('/'), @Get('/:id'), @Post('/') |
+| tsoa | supported | yes: @Route('x') class extends Controller with @Get('{id}') and @Post() |
+| type-graphql | supported | yes: @Resolver class with @Query/@Mutation, served by Apollo on /graphql |
+| Vercel Functions (@vercel/node), no framework | supported | yes: api/<name>.ts default export handler(req: VercelRequest, res: VercelResponse): path from the file, every verb<br>yes: api/<name>.ts exporting GET, POST, ... with web Request and Response: the export name is the verb<br>yes: api/<name>.ts default export { fetch(request) }: one handler for every verb<br>yes: api/index.ts serves /api and api/<dir>/index.ts serves /api/<dir><br>yes: api/<dir>/[param].ts: a bracketed file name is one path segment, value in req.query<br>yes: api/<dir>/[...name].ts outside Next.js: still ONE segment, not a catch-all<br>yes: api/<name>.ts with export const config = { runtime: 'edge' }: same path rule as Node |
+| vercel.json | supported | yes: rewrites: [{ source, destination: '/api/<fn>' }]: the source path is served by that function<br>yes: cleanUrls: true: a function is served without its extension; the extension form only redirects<br>yes: routes: [{ src: <regex>, methods, dest: '/api/<fn>' }]: regex source, optional verbs |
+
+## The language's own HTTP server
+
+0 supported, 0 partly, 3 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| Bun.serve | not yet | no: Bun.serve({ routes: { '/path': { GET, POST } } }) in TS |
+| Deno.serve | not yet | no: Deno.serve(opts, handler) with new URL(req.url).pathname comparison |
+| Deno.serve + URLPattern | not yet | no: new URLPattern({ pathname: '/x/:id' }).exec(req.url) |
+
+## HTTP client libraries (the calls your code makes to other services)
+
+10 supported, 8 partly, 8 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| @angular/common/http | partly | no: provideHttpClient(withInterceptors([...])) in app.config.ts (standalone bootstrap)<br>yes: class AuthInterceptor implements HttpInterceptor registered through HTTP_INTERCEPTORS (adds a header only) |
+| @angular/common/http HttpClient | not yet | no: private http = inject(HttpClient) in a standalone component; this.http.put<T>(`${environment.apiUrl}/path`)<br>no: functional HttpInterceptorFn that puts environment.apiUrl in front of relative URLs; services call this.http.get<T>(relative)<br>no: NgModule app with HttpClientModule; service with constructor(private httpClient: HttpClient); get<T>(`${environment.apiUrl}/x/${id}`, { params })<br>no: constructor(private http: HttpClient); this.http.get<T>(`${environment.x}/path`)<br>no: this.http.post<T>(`${this.base}/path`, body) with the base in a class field<br>no: this.http.delete<T>(url with id) |
+| @apollo/client | supported | yes: useQuery<T>(gql) and useMutation(gql) in a .tsx component, uri on the client in another module<br>yes: new ApolloClient({ uri }); client.query({ query: gql`...` }) |
+| @builder.io/qwik-city | partly | no: export const useX = routeLoader$(async () => fetch(...))<br>yes: server$(async function (...) { fetch(...) }) |
+| @nestjs/axios HttpService | partly | partly: this.httpService.get(url) wrapped in firstValueFrom<br>yes: this.httpService.axiosRef.post(url, body) |
+| @reduxjs/toolkit (RTK Query) | not yet | no: createApi({ baseQuery: fetchBaseQuery({ baseUrl }), endpoints: b => ({ x: b.query({ query: () => 'path' }) }) }) |
+| @tanstack/react-query | supported | yes: useQuery({ queryKey, queryFn }) where queryFn calls fetch<br>yes: useMutation({ mutationFn }) where mutationFn calls axios.post |
+| @trpc/client | not yet | no: createTRPCProxyClient({ links: [httpBatchLink({ url })] }); trpc.ns.proc.query() |
+| axios | partly | no: export const http: AxiosInstance = axios.create({ baseURL: import.meta.env.X ?? default }); http.get<T>(path) in another module<br>partly: const api: AxiosInstance = axios.create({ baseURL }); api.get<T>(path) |
+| ky | supported | yes: ky.get(url).json<T>()<br>yes: ky.create({ prefixUrl }) then api.post(relative, { json }) |
+| next | partly | partly: base URL from process.env.NEXT_PUBLIC_API_URL ?? default in a shared lib module |
+| next (app router) | partly | partly: fetch(url, { next: { revalidate } }) in an async server component |
+| next (middleware) | not yet | no: NextResponse.rewrite(new URL(path, backendOrigin)) in middleware.ts |
+| next (next.config.js) | not yet | no: rewrites() returning { source, destination } that proxies to a backend<br>no: redirects() sending the browser to a backend URL |
+| next (pages router) | supported | yes: export const getServerSideProps: GetServerSideProps = async () => fetch(...) |
+| next (server actions) | partly | partly: 'use server' module exporting an async action that calls fetch |
+| nuxt ($fetch in .vue) | supported | yes: $fetch(url, { method }) in a .vue function |
+| nuxt (useFetch in .vue) | not yet | no: const { data } = await useFetch<T>(url) in <script setup lang="ts"> |
+| nuxt (useFetch in a composable) | not yet | no: useFetch(path, { baseURL }) in composables/*.ts |
+| ofetch | supported | yes: ofetch(url, { method: 'DELETE' }) |
+| ofetch ($fetch, Nuxt) | supported | yes: $fetch(path, { baseURL }) |
+| openapi-fetch | not yet | no: createClient<paths>({ baseUrl }).GET('/path/{id}', { params }) |
+| react-router-dom | supported | yes: route object loader: async ({ params }: LoaderFunctionArgs) => fetch(...) |
+| solid-js | supported | yes: createResource(fetcher) where the fetcher calls fetch |
+| swr | partly | partly: useSWRMutation(url, fetcher with { arg }) in .tsx<br>yes: useSWR(url, fetcher): the key is the URL and the fetcher calls fetch(url) |
+| vue (single-file component, lang ts) | supported | yes: axios.post in <script setup lang="ts"> |
+
+## The language's own HTTP client
+
+2 supported, 1 partly, 5 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| astro (.astro page) | not yet | no: fetch in the --- frontmatter of a .astro page |
+| EventSource (browser) | not yet | no: new EventSource(url) for server-sent events |
+| fetch (browser) | partly | partly: fetch(`${API}/path`) in a function inside useEffect, base from import.meta.env ?? default |
+| fetch (global) | not yet | no: async function http<T>(path, init) { fetch(`${BASE}${path}`, init) }; http<Fare>(`/fares/${id}`) |
+| navigator.sendBeacon (browser) | not yet | no: navigator.sendBeacon(url, data): a POST |
+| svelte (component, lang ts) | supported | yes: fetch in <script lang="ts"> of a .svelte file |
+| WebSocket (browser) | supported | yes: new WebSocket('ws://host/path') |
+| XMLHttpRequest (browser) | not yet | no: xhr.open('POST', url); xhr.send(body) |
+
+## gRPC
+
+3 supported, 1 partly, 1 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| @connectrpc/connect (connect-es) | supported | yes: router.service(Desc, { method(req) {...} }) inside connectNodeAdapter({ routes })<br>yes: createClient(Desc, createConnectTransport({ baseUrl })); client.method(req) |
+| @grpc/grpc-js + ts-proto | not yet | no: server.addService(XService, impl) where impl is a typed const, not an object literal in the call<br>no: new XClient(addr, creds) from makeGenericClientConstructor; client.method(req, cb) |
+| @nestjs/microservices (gRPC transport) | supported | yes: nestjs-grpc-method: @GrpcMethod('Service', 'Method') with package and protoPath in createMicroservice options<br>yes: @GrpcStreamMethod('Service', 'Method') with Observable in and out<br>yes: @GrpcMethod('Service') with the RPC name taken from the method name, capitalised<br>yes: service_lookup: client.getService<T>('Service') then svc.method(req); package and url in ClientsModule.register |
+| grpc-web | supported | yes: new {S}Client(url) from *_grpc_web_pb; client.method(req, metadata, cb)<br>yes: new {S}PromiseClient(url).method(req) |
+| nice-grpc | partly | no: createServer().add(XDefinition, { method(req) {...} }) with ts-proto generic definitions<br>partly: createClient(XDefinition, createChannel(addr)); client.method(req) |
+
+## Databases and data stores
+
+5 supported, 3 partly, 7 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| @libsql/client | supported | yes: client.execute(sql) and client.execute({ sql, args }) |
+| @mikro-orm/core | not yet | no: @Entity({ tableName }); em.find(Entity, q); em.nativeDelete(Entity, q) |
+| @neondatabase/serverless | not yet | no: const sql = neon(url); await sql`SELECT ...` |
+| @nestjs/mongoose | not yet | no: @Schema({ collection }) class; @InjectModel(X.name) private model: Model<X>; this.model.find() |
+| @nestjs/typeorm | not yet | no: constructor(@InjectRepository(Entity) private repo: Repository<Entity>); this.repo.find() |
+| @prisma/client | partly | no: prisma.<model>.findMany/create where schema.prisma maps the model with @@map("table")<br>no: prisma.<model>.findUnique with no @@map: the table is the model name<br>yes: prisma.$queryRaw`SELECT ...` tagged template<br>no: main reads a table another service writes, through its own Prisma schema |
+| @supabase/supabase-js | partly | yes: supabase.from('table').select()/update()<br>no: supabase.storage.from('bucket').upload()<br>yes: main reads a table another service writes |
+| @typegoose/typegoose | not yet | no: @modelOptions({ schemaOptions: { collection } }); getModelForClass(C).find() |
+| @upstash/redis | supported | yes: new Redis({ url, token }).incr/get(key) |
+| @vercel/postgres | supported | yes: sql`SELECT ...` imported from @vercel/postgres |
+| dexie | not yet | no: class X extends Dexie { t!: Table }; db.t.add(); db.t.where().equals().toArray() |
+| drizzle-orm | partly | yes: pgTable('table', cols) in schema.ts; db.select().from(table) / insert(table) / delete(table)<br>no: db.execute(sql`...`) |
+| kysely | supported | yes: db.selectFrom('t').selectAll().execute(); insertInto('t'); deleteFrom('t') |
+| sequelize-typescript | not yet | no: @Table({ tableName }) class X extends Model; X.findAll()/create() |
+| typeorm | supported | yes: @Entity('table') class; dataSource.getRepository(Entity).find()/save()<br>yes: createQueryBuilder().select().from(Entity, 'alias').getOne()<br>yes: dataSource.query(sql, params) |
+
+## Messaging and events (queues, topics, streams)
+
+4 supported, 1 partly, 4 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| @azure/functions (v4) | supported | yes: app.serviceBusQueue('name', { queueName, handler }) |
+| @nestjs/bullmq | not yet | no: @Processor('queue') class extends WorkerHost { process(job) }<br>no: @InjectQueue('queue') private q: Queue; this.q.add('job', data) |
+| @nestjs/event-emitter | supported | yes: this.events.emit('name') and @OnEvent('name') handler |
+| @nestjs/microservices | partly | yes: @MessagePattern('pattern') request-reply handler<br>yes: @EventPattern('pattern') event handler<br>no: @Inject('X') private client: ClientKafka; this.client.emit('pattern', data)<br>no: this.client.send('pattern', data) request-reply |
+| @nestjs/websockets | supported | yes: @SubscribeMessage('event') on a @WebSocketGateway; this.server.emit('event') |
+| AWS SAM template.yaml | not yet | no: Events: Type: SQS Properties: Queue, the handler consumes the queue |
+| inngest | not yet | no: inngest.createFunction({ id }, { event: 'name' }, handler)<br>no: inngest.send({ name, data }) |
+| mitt | supported | yes: const bus = mitt<Events>(); bus.on('x', h); bus.emit('x', data) |
+| socket.io-client | not yet | no: io(url).emit('event') and socket.on('event') in a React component |
+
+## Build tools and package managers
+
+9 supported, 0 partly, 0 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| Angular CLI workspace | supported | yes: angular.json with an application and a library under projects/, ng-package.json, tsconfig paths pointing the library at dist/ |
+| Deno (deno.json imports) | supported | yes: deno.json "imports" map naming a local library folder and jsr:/npm: specifiers; tasks; no package.json |
+| Deno 2 workspaces | supported | yes: root deno.json "workspace": ["./api", "./money"], each member with its own deno.json name and exports |
+| Nx (integrated repo) | supported | yes: nx.json, project.json per project with projectType, no package.json in apps or libs, tsconfig.base.json paths for libs |
+| Nx (package-based repo) | supported | yes: npm workspaces plus nx.json; each package has package.json and a project.json with projectType |
+| tsconfig paths | supported | yes: one app with "baseUrl": "." and "paths": { "@app/*": ["src/*"], "@lib/*": ["lib/*"] }, imports through the aliases |
+| Turborepo | supported | yes: turbo.json tasks, apps/web (Next.js) and apps/api (fastify), packages/ui, plus config-only packages (tsconfig, eslint-config) |
+| TypeScript project references | supported | yes: root tsconfig.json "references" to packages/core and packages/server, composite true, outDir lib/ per package; no workspaces |
+| Vite | supported | yes: vite.config.ts resolve.alias "@" to src and "~ui" to a sibling package folder, dist/ output, plus tsconfig paths for the same "@" |
+
+## Project and folder layouts
+
+3 supported, 0 partly, 0 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| code generators (GraphQL codegen, Relay, OpenAPI, Prisma) | supported | yes: src/gen/ with a "generated, do not edit" header, __generated__/ next to components, prisma client in node_modules |
+| Next.js (app router) | supported | yes: src/app/ with route.ts handlers and server components, src/lib helpers, "@/*" alias, .next/ output |
+| Storybook | supported | yes: .storybook/ config, *.stories.tsx next to components, storybook-static/ build output |
+
+## Deployment files
+
+1 supported, 0 partly, 0 not yet.
+
+| Name | Status | Ways of using it that were tested |
+|---|---|---|
+| docker-compose.yml at the monorepo root | supported | yes: compose services with build: ./apps/x and build: { context: ., dockerfile: apps/y/Dockerfile }, init ONCE at the repository root<br>yes: the same repository, but each app folder added to one project with its own `niro-local init` (how the coverage-run monorepos were measured) |

package/docs/tokens-speed-and-accuracy.md

@@ -0,0 +1,99 @@
+# Tokens, speed and accuracy
+
+**This page explains how Niro measures tokens, speed and accuracy, and how you can measure them on your own work.** It does not give typical savings: they change from one task to the next and from one person to the next. Where a sentence is reasoning rather than measurement, it says so.
+
+Words used on this page:
+- a **token** is the unit a language model reads and is billed by, roughly half a word of code;
+- a **session** is one conversation with a coding agent;
+- **cache reads** are the tokens of the conversation so far, which the model re-reads, at a lower price, on every turn;
+- **cache writes** are new tokens added to that stored conversation, billed once at a higher price;
+- **MCP** (the Model Context Protocol) is the standard way a coding agent calls outside tools such as Niro's.
+
+## How tokens are counted
+
+**Characters, divided by 2.09.** Niro counts the characters of every answer it returns, and turns them into tokens at 2.09 characters a token. That rate was measured against the model's own token counts, in Keycloak A/B transcripts, on results of more than 2,000 characters each. Over 69 Niro answers the median was 2.09 (middle half 1.83 to 2.25). Over 367 shell-tool results it was 2.10. Code and file paths pack more tokens into a character than English prose, for which 4 characters a token is the usual rule of thumb.
+<!-- source: niro-local src/niro_local/mcp/receipt.py:27-33 (CHARS_PER_TOKEN = 2.09 and its measurement note); scratchpad niro-local-receipt-tokens/HOW-MEASURED-AND-VERDICT.md (table "Tool output | Results | Real characters per token, median": 69 niro-local answers 2.09, 1.83 to 2.25; 367 native 2.10) -->
+
+The end-of-task line uses this rate on both of its sides, so the comparison between them does not depend on it.
+
+## How the by-hand figure is estimated
+
+The end-of-task line and `niro impact` compare what Niro's answers cost with an estimate of finding the same things with text searches and file reads. The estimate follows how agents with only shell tools were seen to work: one search per name asked about, then about 40 lines read around each place an answer showed you, and one more search for what a name search cannot reach, such as the classes that run behind an interface. Only what you were shown is priced. The full method, with a worked example of the arithmetic, is in [evaluate-what-niro-did.md](evaluate-what-niro-did.md).
+<!-- source: niro-local src/niro_local/mcp/by_hand.py:1-38 (the method; READ_LINES = 40, MAX_GREP_LINES = 250); docs/evaluate-what-niro-did.md section 1 -->
+
+**How the estimate is checked.** It is compared with real A/B runs: what the shell-only session of a task really read, less what the Niro session of the same task still read with shell tools. In our A/B runs so far, added up over the tasks that printed a token figure, the two came close. For one task they can differ by several times either way, because the two sessions did not make the same searches. So read a single line's "instead of" as a rough order of size, not as a measurement.
+<!-- source: scratchpad niro-cli-task-playbooks/AB-RESULTS.md "Receipt figures against measured tokens"; ab/receipt-adjusted.json (python3 -I ab/replay_receipts.py p1 p2) -->
+
+## How look-ups and round trips are counted
+
+`niro impact` also counts, from the answers themselves, how many searches and file reads they stood for, and how many waits one after another an agent working by hand would have needed (a walk three levels deep needs at least three searches in a row). Both are counted from what each answer covered; neither is typed by the agent. How each is counted is in section 3 of [evaluate-what-niro-did.md](evaluate-what-niro-did.md).
+<!-- source: niro-local src/niro_local/mcp/round_trips.py; src/niro_local/journal/store.py trips_avoided, levels_avoided -->
+
+## How the `answer` input was measured
+
+The `answer` input asks for a short form of an answer, such as a count, the names, or the places only ([answer-shapes.md](answer-shapes.md)). To decide which forms to build, recorded Niro calls from real sessions were read together with what the agent did next. For each call, the smallest short form that still held what the agent then used was applied to the real answer text, and the tokens before and after were compared. The shapes were then run again on the release engine, on the calls whose code still existed, to check that estimate against real answers.
+<!-- source: scratchpad niro-local-answer-shapes/page-data.json and BRIEF.md (the trial); niro-local docs/usecases/answer-shapes.md "What the replay showed (2026-11-10)" -->
+
+**Why a short answer pays more than once.** This is reasoning, not a measurement. An answer stays in the conversation for every later turn, so a shorter answer is cheaper on every turn that follows it, not only on the turn that asked for it.
+
+## How we run an A/B, and how you can
+
+**What an A/B is.** The same task is run twice: once with Niro and once without, with everything else the same. Ours are run like this:
+- each task has an answer key, a list of facts read from the source by hand before any run;
+- each session runs in headless Claude Code, on one pinned version with auto-update off, on the same model;
+- each session starts with no project instructions and no memory, and with web tools off;
+- the "without" arm has shell and file tools only; the "with" arm has the same tools plus Niro, over MCP or from the shell;
+- in the "with" arm, `mark_task_complete` is blocked, so the end-of-task call a real session makes is not in its cost;
+- in our latest runs, the "with" arm also had six lines of guidance asking it to use the `answer` input where it fits. niro-cli does not install those lines, and no run measured how much they helped;
+- a blind reviewer marks each fact found or missed, with tool names removed from the answers, and counts anything invented;
+- cost, wall time, tool calls, cache writes, cache reads and output tokens are read from each session's own result event.
+<!-- source: scratchpad niro-local-tool-parity/ab-keycloak/bench.py and RESULTS-76-questions.md header; scratchpad niro-cli-task-playbooks/AB-PLAN.md and ab/bench.py (session_cmd blocks mcp__niro-local__mark_task_complete in the Niro arm; parse_stream); ab/answer-shapes-guide.md (the six lines) -->
+
+**Why Niro over MCP can save less than Niro from the shell.** An MCP answer enters the conversation whole. A shell command's output can be cut with `grep` or `head` before it does. The `answer` input is how an agent asks for a shorter answer inside MCP.
+<!-- source: scratchpad niro-local-receipt-tokens/HOW-MEASURED-AND-VERDICT.md ("it behaves like the native tools do: the agent runs it in the shell, can filter its output with grep or head, and only the final text enters the main conversation"); niro-local docs/usecases/answer-shapes.md "What it is" -->
+
+**A run can show that the answer key is wrong.** In one of our tasks, both arms, in both runs, left out tests that the key named, and said why: at run time those tests never reach the method. Reading the code confirmed it, so the key was corrected and both arms were scored against the corrected key. When the two arms agree against your key, check the key against the code before you score.
+<!-- source: scratchpad niro-cli-task-playbooks/AB-RESULTS.md "Key correction" (task p-03); keycloak model/storage/.../UserCredentialManager.java:310-316 -->
+
+**Limits we keep in mind.** With one or two runs per task, one fact or a few cents on one task is within run-to-run noise, so compare totals over many tasks. Results from one agent version should not be compared with another version's. Our runs so far ask questions about code; none measured a full edit with its tests.
+<!-- source: scratchpad niro-cli-task-playbooks/AB-PLAN.md "What is not measured"; niro-local-tool-parity/ab-keycloak/RESULTS-76-questions.md "Caveats" -->
+
+To run your own, with the switch that turns Niro off for one Claude Code session and the numbers worth comparing, see section 4 of [evaluate-what-niro-did.md](evaluate-what-niro-did.md).
+
+## How accuracy pays off over a long session
+
+**What is measured.** In our Keycloak A/B runs, cache reads were most of the tokens in both arms. So most of a session's tokens are the conversation being re-read on each turn, and anything that enters the conversation is paid for again on every later turn.
+<!-- source: scratchpad niro-local-tool-parity/ab-keycloak/RESULTS-76-questions.md "Token detail" (cache reads against all tokens, both arms) -->
+
+**What follows, as reasoning (not measured).** A missed caller costs more than the search that missed it:
+
+1. The agent lists callers with a text search and misses one that goes through an interface. In one of our Keycloak A/B sets, every fact the shell-only agent missed was of this kind.
+2. It edits the method and updates the callers it found. The missed caller now passes the wrong value.
+3. A test fails later in the session, or the bug ships. The agent goes back: it searches again, reads the files again, and reads the failing test's output. Each of those results enters the conversation.
+4. Every later turn re-reads all of that. A longer conversation also reaches the agent's context limit sooner, and the agent then compacts it (replaces the history with a summary), which drops detail it may need.
+<!-- source: step 1: scratchpad niro-local-receipt-recheck/NATIVE-CHOICES.md ("Every one of the 21 c4 misses is 'Implementations of <Interface>.<method>'"; read by hand) -->
+
+A list that says "complete" when it is, and "PARTIAL" with what was cut when it is not, avoids step 3. Niro's lists also have known gaps, and they are listed in [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md); the playbooks show where to check with a text search.
+
+## Speed
+
+| What | Measured | Where |
+|---|---|---|
+| A Niro call through MCP, warm | 0.04 to 0.07 s | the code-mode timing run, 10 calls each |
+| The same call through `niro ask` (a new process each time) | about 0.45 s | same run |
+| Full build of Keycloak (9,103 files) | 182 s | same run, machine load about 2 |
+| Full build of Keycloak, for these docs | 3 min 17 s | the build log, 4 parse workers, load not recorded |
+<!-- source: scratchpad niro-coverage-run/plans/code-mode.md ("A `niro ask` call takes 0.45 s against 0.04 to 0.07 s for the same call to a warm MCP server"); niro-coverage-run/code-mode-timing/README.md ("logs/init.log: the Keycloak build (9,103 files, 182 s)"); niro-coverage-run/plans/code-mode.md:70 ("load 1.9 to 2.1"); scratchpad niro-cli-task-playbooks/build-keycloak.log ("real 3m16.849s"; heavy-run.sh sets NIRO_LOCAL_PARSE_WORKERS=4) -->
+
+A build's time depends on the size of your code, the number of cores and how busy the machine is.
+
+## What is not measured yet
+
+- **Edits.** Every A/B so far asked questions about code; none measured a full change with its tests.
+- **Many runs per question.** Our A/B runs ran each question once or twice per arm.
+- **Helper agents.** No run in any Keycloak set started one, so the pattern where a helper does the reading and returns a summary is not measured either way.
+<!-- source: scratchpad niro-local-receipt-tokens/HOW-MEASURED-AND-VERDICT.md "Helper agents" ("no run in either arm started a helper agent") and "How sure this is"; scratchpad niro-cli-task-playbooks/AB-PLAN.md "What is not measured" -->
+
+## Related
+
+[evaluate-what-niro-did.md](evaluate-what-niro-did.md) (the end-of-task line, `niro impact`, and how to run your own A/B), [answer-shapes.md](answer-shapes.md), [lifecycle-overview.md](lifecycle-overview.md).

package/docs/troubleshooting.md

@@ -0,0 +1,42 @@
+# Troubleshooting
+
+**Start with three commands.** Most problems show up in one of them.
+
+```
+niro status          # this folder: indexed? built when? plan, sharing, agent, background updates
+niro engine status   # the engine: installed? where? does its database open?
+niro plan            # your plan and lines used
+```
+<!-- source: src/commands/status.js:76-88; src/commands/engine.js:81-118; src/commands/plan.js:57-86 -->
+
+**Then find your message.** [reference-messages.md](reference-messages.md) lists every message that has an answer, with a link to it.
+
+## By kind of problem
+
+| Problem | Page |
+|---|---|
+| Installing, the engine, the background watcher | [faq-install-and-setup.md](faq-install-and-setup.md) |
+| Signing in, your account | [faq-login-and-account.md](faq-login-and-account.md) |
+| The line limit, the licence | [faq-licence-and-plans.md](faq-licence-and-plans.md) |
+| Building the graph, files left out | [faq-indexing.md](faq-indexing.md) |
+| An answer is wrong or missing something | [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md) |
+| Your coding agent does not see or use Niro | [faq-assistants-and-mcp.md](faq-assistants-and-mcp.md) |
+| Branches, worktrees, temporary projects | [faq-worktrees-and-branches.md](faq-worktrees-and-branches.md) |
+| What is sent, secrets, files Niro reads | [faq-privacy-and-security.md](faq-privacy-and-security.md) |
+| Slow builds or answers, disk use | [faq-performance.md](faq-performance.md) |
+| Upgrading | [faq-updates.md](faq-updates.md) |
+| Removing Niro | [faq-uninstall.md](faq-uninstall.md) |
+| Working without a network | [faq-offline.md](faq-offline.md) |
+| The end-of-task line, feedback | [faq-feedback-and-receipts.md](faq-feedback-and-receipts.md) |
+| Pull request review, root cause analysis | [hosted-only.md](hosted-only.md) |
+
+## Still stuck
+
+Email **help@niro.ai** with:
+
+- the command you ran;
+- the message you saw;
+- the output of `niro status` and `niro engine status`.
+
+Remove anything private from them first.
+<!-- source: help@niro.ai: Niraj, 2026-11-10 -->

package/docs/uninstall.md

@@ -0,0 +1,74 @@
+# Uninstalling Niro Local
+
+## Remove one folder
+
+To stop indexing one repo and free its lines, without removing Niro:
+
+```bash
+niro plan remove ~/code/old-service
+```
+
+Its graph is deleted; the folder and your code are not touched. Run `niro init` in it later to
+index it again.
+<!-- source: src/commands/plan.js:76-86 (niro plan remove); niro-local src/niro_local/cli.py:350 (remove: the folder's graph is removed and it is forgotten) -->
+
+## Remove Niro from this machine
+
+```bash
+niro uninstall
+```
+
+It lists what it will remove and asks first (`--yes` skips the question, for scripts):
+
+1. **Niro's entries in your AI assistants' settings**, for every assistant `niro mcp install`
+   configured: the `niro` MCP server, the Niro skills (`niro-skill`, `niro-local`), the hooks, and
+   the Niro section in files such as `~/.claude/CLAUDE.md`. Your own settings are left as they were.
+2. **The background watcher** (`niro-watch` in PM2). What happens to PM2's own start-at-login entry
+   depends on your computer. If PM2 still runs other programs, the entry is kept, because it is not
+   Niro's. On macOS, with nothing else in PM2, it is removed. Otherwise (on Linux), removing it needs
+   administrator rights, so the uninstall prints the command for you to run.
+3. **`~/.niro`**: your sign-in, settings and the local engine.
+4. **`~/.niro-local`**: the list of indexed folders and every graph (`graph.db`).
+<!-- source: src/commands/uninstall.js:4-12 (the order of steps), :86-113 (lists, then asks; --yes), :141-160 (assistants, watcher, ~/.niro-local, ~/.niro), :150, :169-171 ("PM2 still starts on login (with nothing of Niro's). To remove that too: ..."); src/lib/service.js:301-328 (kept when PM2 runs other programs; the macOS LaunchAgents file removed; otherwise the `pm2 unstartup` command printed); src/mcp/teardown.js:1-27 (what an assistant's entry holds) -->
+
+A step that fails is reported and the others still run. Then remove the command itself:
+
+```bash
+npm uninstall -g @niroai/niro
+```
+
+Restart your assistants so they stop loading the removed entries.
+<!-- source: src/commands/uninstall.js:146-171 (a failed step sets the exit code and the rest still run; the two last steps printed) -->
+
+## Remove only the assistant connection
+
+To keep the graphs but disconnect an assistant:
+
+```bash
+niro mcp uninstall --client claude-code     # one assistant
+niro mcp uninstall --all                    # every assistant
+```
+<!-- source: src/mcp/teardown.js:1-27, :645-653 -->
+
+## By hand, if `niro` will not run
+
+1. Assistant settings. For Claude Code: `claude mcp remove niro --scope user`, then delete
+   `~/.claude/skills/niro-skill` and `~/.claude/skills/niro-local`, and remove the block starting
+   with the Niro marker from `~/.claude/CLAUDE.md`. Other assistants: remove the `niro` server from
+   their MCP settings, and delete `~/.agents/skills/niro-skill` and `~/.agents/skills/niro-local`.
+2. The watcher: `pm2 delete niro-watch && pm2 save`.
+3. The data: `rm -rf ~/.niro ~/.niro-local`.
+4. The command: `npm uninstall -g @niroai/niro`.
+<!-- source: src/mcp/setup.js:738-755, :1928-1985, :2393-2427 (where the entries and skills are written); src/commands/start.js:390-411 (the watcher is the PM2 process niro-watch); src/commands/uninstall.js:66-67 (~/.niro and ~/.niro-local) -->
+
+## Your account
+
+<!-- source: src/commands/uninstall.js:94-101 ("Your Niro account stays"; code sharing is not turned off); src/lib/planUsage.js:116-119 (the sentence below) -->
+Uninstalling removes Niro from this machine only; your Niro account stays. If you turned on code
+sharing, turn it off under Settings, Privacy in the console first, so no machine you use can send
+a whole repository any more. With sharing off, this still leaves a machine where Niro is
+installed. Your code stays on this machine, except, for each line the audit flags, the whole method that
+holds it and one line for each name it uses, sent with secrets masked and author and company names removed. A record of which
+Niro tools your assistant used is also sent, to improve Niro and to show you its value. Niro's
+tools answer your assistant from the graph on this machine and never send the contents of your
+files.