Client-side orientation and efficient navigation

The working model: many documents, agent-mediated

Oddlynew is built for working with a lot. An organization is not a tidy notebook where someone keeps a hundred documents and decides carefully where each one goes. Organizations can grow into thousands of documents. Historical evidence, decisions, research, drafts, observations, and handoffs may remain available when they retain value, but they do not all remain current guidance. Agents should keep the owning documents clear, consolidate reusable understanding, and archive or demote material that no longer belongs in active attention. The person you work for does not navigate the whole space directly. You do. A session rarely means working on one document; it means searching across many, reading slices of several, and editing a few.

That scale is a feature, and it stays fast only if you navigate it well. The difference between an efficient and an inefficient agent in a large organization is not intelligence. It is whether you arrive with coordinates.

Store coordinates, not content

If your agent client retains context across sessions, use that only for coordinates, not as the source of the work. The documents themselves live in Oddlynew; never duplicate their content into client-retained context because the copy goes stale the moment someone edits the original. Useful coordinates include organization ids, a few load-bearing document ids, metadata conventions, type ids, and the person's current goal.

The organization ids you work in, and what each one is for.
The document ids of the few load-bearing documents you return to: the organization's guidance document, the tracker for current work, the type definitions you write against.
The organization's metadata conventions, meaning which keys exist and which values matter (status values, topics, owners). These are the filters you will need next session.
The type ids of the document types you create regularly.
What the person is currently working toward. Search is only as good as the question, and the question comes from knowing the goal.

Oddlynew will find the needle in the haystack either way, but there are faster and slower routes into it. Coordinates put you in at the right height: the right organization, the right type, the right metadata key, the date range of the work. From there the needle is one or two calls away. Without them you can still get there, but you spend the session walking the haystack.

Navigation practices at scale

The mechanics of each call are in Search and metadata. What follows is how to use them once the corpus is large.

Filter before you read. Prefer a filtered search over broad listing: constrain recent work with updatedAfter, a known workflow with typeIds, or a metadata filter. Use listMetadataValues to discover which values exist rather than guessing them, because an invented value returns an empty page instead of an error. An unknown field is different: listMetadataValues throws instead of returning an empty list, and the message names the attributes that are declared, which is discovery in its own right.

Choose the search mode deliberately. Use hybrid for most questions, exact for identifiers and known phrases (a literal, case-insensitive substring match), and semantic when you only know the meaning. hybrid and semantic depend on a configured embedding rollout; when the deployment has none, they fail naming the mode you asked for and fts is the fallback.

Read progressively. Take envelope and outline first, then section or slice around the block that matters. Pull expand only when you genuinely need all of it. A large organization stays fast for you when your reads stay bounded.
Write for future retrieval. Set meaningful metadata when you create a document; the filters that make next session fast are the ones you set this session. Cite related documents with docrefs, so backlinks become a navigation surface.
Refresh the map when it fails. Client-retained context holds hypotheses, not guarantees. If a stored id or convention stops matching, re-derive it from the organization and correct the coordinate.

Coordinates collapse into a single call, and the search result carries everything the follow-up read needs:

const found = await documents.search({
  organizationId: "0193b1f2-8c44-7a10-9f3b-2d5c1e77aa01",
  query: "retention policy exceptions",
  typeIds: ["0193a0c1-77aa-7bd2-91e6-45f3c0aa1101"],
  updatedAfter: "2026-06-01",
  metadataFilters: [{ field: "status", op: "eq", value: "active" }],
  limit: 10,
})
const top = found.results[0]
const key = top && top.matches[0] && top.matches[0].primaryBlockKey
if (!key) return { found: false }
return await documents.getDocument({
  documentId: top.documentId,
  version: top.version,
  scope: { type: "slice", blockKey: key, above: 2, below: 2 },
})

Every filter narrows what the ranked pass has to consider, and version pins the follow-up read to the snapshot that was actually searched.

The first session, and every session after

On first contact with an organization, invest. Read its guidance document, list its types, sample its metadata conventions, and retain only the small map of coordinates your client can reuse. Do not copy document contents into that map.

const organizationId = "0193b1f2-8c44-7a10-9f3b-2d5c1e77aa01"
const types = await documents.listTypes({ organizationId })
const statuses = await documents.listMetadataValues({ organizationId, field: "status" })
return {
  types: types.types.map(t => ({ id: t.id, name: t.name })),
  statuses: statuses.values.map(v => v.value),
}

Every later session should start from that map: a few targeted calls instead of a fresh exploration. That is the compounding loop. The organization compounds useful work for the people who own it; the client merely retains enough coordinates to get back there efficiently.