# Reasoning about an institution in Flomio

Flomio is for work that persists between people and over time: someone is
responsible, evidence supports a decision, an outcome creates further work, and
the organisation must later explain what happened and who could see it.

Start with one process or team. A whole company need not move at once. For a
one-off calculation, document or personal checklist, an ordinary tool is usually
enough. Flomio becomes useful when durable responsibility, shared records,
controlled disclosure and accountable changes must work together.

This guide explains the administrative model. It is not a promise that every
capability is available through every deployed interface. Discover the actual
server's capabilities and limits before proposing a live design.

## Begin with the organisation

Ask for a real example from beginning to end. Identify the people involved,
what they know, what they decide, what remains outstanding and who must not see
each part. Distinguish supplied facts, assumptions and missing information.
Include a refusal, a correction and a handover that could naturally occur.

Translate the example into a small arrangement:

| Ordinary language | Starting point in Flomio |
| --- | --- |
| “Keep the customer/equipment/member details” | A standing record with durable identity |
| “Each application or visit needs its own evidence” | A job running a versioned process |
| “The coordinator decides” | A position, its actual holder and a named outcome |
| “Someone from reception can take this” | Work waiting for eligible people; verify actual admission |
| “We promised these checks by these dates” | Owed items created by an admitted plan |
| “That check fulfils this promise” | A declared fulfilment rule with matching subject and work kind |
| “Only staff should see this” | A real privacy boundary, verified from the recipient's view |
| “What happened last month?” | A Number with an explicit population, time basis and evidence interpretation |

These are starting points, not substitutions for policy. A field called
“approved” does not automatically grant authority, create a promise or publish
information. Links connect identities; they do not transfer permissions.

## Facts, identity and evidence

A standing record describes a durable subject. A job records a particular
episode involving that subject. Repeated visits should share a subject identity
and keep separate visit evidence. Do not join people or cases by matching names.

An answer is an assertion made by a person at a recorded point in history.
A named outcome says what that person actually did with the evidence. Design
outcomes in the organisation's language: approve, refuse, refer, accept a repair,
or record that a check failed. Do not infer a decision merely because a score
or text field has a convenient value.

Keep an external event separate from its administrative recording. Recording
“payment confirmed” does not transfer money. An unsigned agreement, unknown
settlement or missing proof stays outstanding until evidence is actually supplied.
Synthetic examples must be labelled as synthetic and kept out of live records.

## Responsibility and authority

Positions preserve organisational responsibility when people change. People
remain the authors of their past actions after they leave. Give a new holder
their own identity; do not rename an old account to become its replacement.

Being able to read, being assigned work, holding a position and being allowed to
change an institution are different facts. A process restriction can narrow who
may act; it does not grant missing authority. Test with the actual separate
accounts, including the person who should be refused.

For live access, call `flomio_list_organisations`. Each organisation includes
your native account `bindings`, with `institution`, `actor` and `effective`.
Pass an effective binding's `institution` to `flomio_open_institution`, then
choose an actor it currently grants. `organisation_id` identifies the customer
organisation and is not the institution ID. Membership alone does not grant an
acting person. Empty or ineffective bindings require an authorised access
change; never invent an actor or substitute another identifier.

Connecting a sign-in account to a person grants that person’s existing access,
including earlier information and pending work. Review the exact recipient and
scope before confirmation. It is not a grant limited to the next task. Native
account-link review checks the control state; it does not certify private
institutional permissions or a human’s intended privacy boundary.

A handover of current work and reassignment of outstanding promises are distinct
acts. Check both after personnel changes. Historical authorship should remain
unchanged. Where an outcome requires independent judgment, verify that the same
person cannot satisfy both responsibilities merely by holding two positions.

## Obligations and fulfilment

Model a promise when the organisation has actually incurred it. An admitted plan
can create a finite set of owed items with subjects, due dates and responsible
positions. An owed-work screen reports admitted promises; it is not evidence
that every promise the organisation ought to have made has been entered.

Fulfilment depends on the declared completion and its relationship to the owed
item. A helpful note or unrelated finished job is not fulfilment. Changing terms,
reassigning responsibility and closing an item with a reason are accountable acts;
they should not erase the original promise or fabricate successful performance.

## Privacy is part of the design

Decide audiences before collecting sensitive evidence. The person doing a stage
is not necessarily the only person who can read the job. People with access to
its department, responsibility or a specific release may also have access.
Offering a process to someone is different from deciding which resulting
evidence they should see. Labels, hidden controls and omitted links are not
privacy boundaries.

**Counterexample:** Common Ground's applicant-facing award work contained an
internal budget reconciliation and private conflict information. Both browser
and operator correctly disclosed what had been put within the applicant's
scope. Their agreement proved interface parity, not a safe design.

Use separate private staff work and narrowly disclosed correspondence when their
audiences differ. Release the appropriate decision explicitly, linked to its
source where useful. A recipient may see a decision without seeing the linked
review. Check the recipient's actual readings, including earlier answers and
cross-case references, before putting real information there.

For an access or organisational change, inspect what existing information becomes
readable, not just the new person's next task. Correcting access later preserves
history but cannot make previously disclosed information unknown again.

## Corrections and organisational change

Use the supported correction path, identifying the assertion being replaced and
why. Respect its approval responsibility. Never edit history to make a mistaken
fact disappear. If that field does not support amendment, an explicit linked
replacement or a recorded exception may be necessary. Explain what remains true
in the original record.

New process versions govern new jobs; existing jobs retain their admitted
interpretation. A new label or compatible field change does not prove an old
report still selects the intended population. Check representative older and
newer cases after changes. Distinguish recorded time from a supplied business
date and from an effective date that a particular capability actually honours.
Putting a future date in descriptive text does not schedule an institutional change.

## Numbers and unknowns

Before proposing a figure, state its question precisely:

1. Which records, jobs, outcomes or owed items are members?
2. Is each member counted, each subject counted once, or each contribution counted?
3. Which process/schema versions are included?
4. Does the figure use evidence accepted at the outcome or subsequently amended evidence?
5. Which business or recorded time determines membership?
6. What happens when that time or the measured value is missing?
7. Who may read the figure and its contributions?

Inspect contributions as well as totals. Missing is not zero, false, on-time or
outside a period. A share among known answers is a different statement from a
share of all cases. An all-time count and a dated count answer different questions.

**Counterexample:** Tan & Associates had 22 of 23 review dates missing. Filling
them from unrelated events, or silently treating those records as outside the
period, would manufacture certainty. The generalisation programme made temporal
membership explicit; it did not make every join, finite selection or conversion
cohort expressible. Check current support rather than inventing a calculation
that appears authoritative.

## Judgment, composition and effort

Keep legitimate discretion with its accountable person. Common Ground's scores
did not create an entitlement to a grant. A late-evidence exception required a
decision and a reason. Its portfolio budget was reconciled by a human; a bound
on each award was not an atomic cap across all awards.

Compose existing ideas before requesting a new one. Private staff decisions,
public correspondence, promised follow-up and a contribution-based Number can
serve a new organisation without inventing an industry-specific object.

Still measure effort. Re-entering evidence, matching cases, selecting the same
records repeatedly and repairing access can be unacceptable even when the model
expresses the result. Classify the difficulty: usability, implementation,
integration, performance, missing convenience, local policy, human judgment,
surface divergence, or a requirement the model genuinely cannot represent.
Do not call a manual workaround an automatic guarantee.

## Experiment, propose, operate

Use an isolated sandbox when the fit is uncertain. Label fixtures, try negative
cases and keep external effects disabled. A successful synthetic lifecycle is
evidence about the arrangement, not permission to establish it for the user.

In this gateway, discover `topic: "sandbox"` to check whether a separate native
evaluation service is enabled. With explicit sandbox permission, create one
synthetic experiment, read its native map and actions, propose a change, inspect
the consequences, then apply its exact review digest. Retain evidence before
discard or expiry: both close access, including retries, without deleting native
history. This initial sandbox has one authenticated author; simulated people
do not establish multi-account privacy. Nothing is promoted into a live institution.

Discover `topic: "grammar"` for the authoring index, then `grammar_topic` or
`grammar_search`, then `grammar_view: "schema"` or `"example"` to inspect one
level at a time. This reference is extracted from the packaged native executable;
each gateway tool still has its own supported scope. Use `flomio_preview_definition`
(or `flomio_sandbox_preview_definition`) to check native publication admission and
audiences without saving a proposal. A preview does not approve or publish it.
Audience review and admission rehearsal answer different questions. Neither
proves that a valid institution expresses the policy you intended.

The subsequent cold-agent CLI study demonstrated two useful counterexamples:
a fixed one-unit limit did not check current stock, and separate references to
an approved edition and a submitted packet did not enforce that they named the
same edition. Test each claimed relationship directly with a legitimate case
and an otherwise equivalent violating case. A generic refusal, malformed input
or another failed precondition cannot establish the rule you meant to test.

Present a proposal in ordinary terms: records kept, decisions made, responsible
people, audiences, outstanding work, reports, manual duties and limitations.
Obtain the required human authority before consequential live changes. Tool
access is not consent to adopt an institution or broaden disclosure.

When operating, inspect current work and use the supported institutional act.
In the agent interface, `flomio_discover` with `topic: "readings"` describes
the available questions. `work_queue` finds pending work; `work_starts` finds
processes available to start. `work` reads recorded answers, and
`work_occurrences` preserves their original form. Read `definitions` for fields
and versions before supplying values. Department and record histories use
current access; an earlier fact does not restore an earlier permission.
Use `flomio_propose_work` to start a disclosed process or complete a current step,
and `flomio_propose_record` to create, correct or retire a standing record. Copy
native schema identities and expected revisions; never calculate them. Record
values are a complete replacement, not a patch. Work answers and record cells use
the same typed values; omitted or unknown facts must not become invented values.
These proposals rehearse native admission and show the exact request for human
review. They do not certify privacy or guarantee saving. Publication and access
changes have their own consequence reviews. Other typed operations and agent
file upload are not yet exposed by this gateway; discover actual support first.

Retain the exact request identity for recovery. After a lost response, reconcile
or retry that same request; do not invent a new identity to make uncertainty go
away. After a refusal, use its structured reason and fresh permitted state.
Do not guess hidden facts or weaken the policy to force completion.

Judge success by the resulting history, current responsibility, fulfilment and
recipient visibility. A successful HTTP response is insufficient. Browser,
operator and agent interfaces should express the same institutional act; report
differences in their consequences rather than differences in their clicks.

The fifteen-company corpus supports this grammar within its tested scope. It
also preserves failed attempts, manual boundaries and a real authoring privacy
counterexample. It is evidence to reason from, not a certification of your design.