Your agent should know
what your app is supposed to do.

# Team access & permissions

Northstar is a shared workspace for a commerce team. A person’s role determines what they can change, from inviting a teammate to issuing a refund.

## Expected behavior

An invitation preserves the role selected by its sender.

Owners and admins can invite editors and viewers. Accepting an invitation grants exactly that role; it never promotes someone to owner.

## Who can do what

| Role | Invite teammates | Manage orders |
| --- | --- | --- |
| Owner | Yes | Edit & refund |
| Admin | Yes | Edit & refund |
| Editor | No | Edit & refund |
| Viewer | No | Read only |

## References

- src/team/invitations.ts
- src/auth/permissions.ts
- /settings/team

## Flows

- invite-member
- accept-invitation
- verify-role

Invite a viewer, accept as that person, then confirm that order editing is unavailable.

## Still to explore

An invitation sent before its sender changes role has not been explored.

# Invite a teammate

Maya manages the Northstar store. She invites Alex to check order statuses without changing orders or customer data.

## Expected behavior

Alex joins the same workspace with the Viewer role.

The invitation is tied to Alex’s email address and selected role. Signing in with a different address must not accept it.

## At each step

| Step | Expected behavior |
| --- | --- |
| Send invitation | Email and selected role appear in pending invitations. |
| Accept invitation | The invited address is verified before joining. |
| Open the workspace | Orders are readable; editing controls are unavailable. |

## References

- src/team/invitations.ts
- src/auth/accept-invitation.ts
- /join

## Flows

- invite-member
- accept-invitation
- verify-role

The accepted membership has the same workspace, email address and role as the invitation.

## Still to explore

Expired invitations still need a separate journey.

# Checkout totals

A customer buys two Field notebooks with a ten-percent discount. Checkout, payment and the confirmation email must agree on the amount paid.

## Expected behavior

Charge the total the customer approved at checkout.

Apply the discount to merchandise before adding shipping. Store monetary amounts in cents and round the discount once, for the whole order.

## Worked example · USD

| Line item | Amount |
| --- | --- |
| 2 × Field notebook | $40.00 |
| WELCOME10 · 10% off merchandise | −$4.00 |
| Standard shipping | $5.00 |
| Total charged | $41.00 |

## References

- src/orders/checkout.ts
- src/orders/totals.ts
- /checkout

## Flows

- seed-cart
- place-order
- verify-total

Checkout total = payment amount = saved order total = email receipt total.

## Still to explore

Combining discount codes is not documented.

# Refunds & returned stock

An owner, admin or editor can fully refund a paid order before dispatch. The customer gets back the amount paid, including standard shipping.

## Expected behavior

A full refund reverses the payment and returns the items to stock.

For the notebook order, return $41.00 and restore two notebooks. Repeating the request must not refund or restock the order twice.

## Expected changes

| Record | Before | After |
| --- | --- | --- |
| Order | Paid | Refunded |
| Refunded amount | $0.00 | $41.00 |
| Available notebooks | 18 | 20 |

## References

- src/orders/refunds.ts
- src/inventory/adjust-stock.ts
- /orders/order-1042

## Flows

- place-order
- refund-order
- verify-refund

The payment, order status and inventory agree after the refund. A second request changes none of them.

## Still to explore

Partial refunds and returns after dispatch are not covered by this rule.

# The language of Northstar

Use these terms when describing business rules and writing flows. A workspace is the team’s shared store, not an individual’s account.

## Expected behavior

A membership connects one person to one workspace and one role.

The same person may belong to several workspaces. Permissions are evaluated within the workspace they are using.

## Terms used in this application

| Term | Meaning |
| --- | --- |
| Workspace | A store, its orders and its team. |
| Membership | A person’s role in one workspace. |
| Invitation | A pending offer of membership to an email address. |
| Available stock | Units that can be sold; excludes units in paid orders. |

## References

- src/team/membership.ts
- src/inventory/stock.ts
- /settings/team

## Flows

- switch-workspace
- verify-role

Switching workspace uses the membership for the destination, not the previous workspace.

## Still to explore

Guest access is not defined in the current application model.

# Application routes

A generated route index provides starting points for exploration. A route’s presence does not establish its expected behavior or test coverage.

## Expected behavior

Read the business rules alongside the route index.

The agent records observations in authored documents after inspecting the source and exploring the application.

## Discovered routes

| Path | Purpose |
| --- | --- |
| /settings/team | Members and pending invitations |
| /join | Accept an invitation |
| /checkout | Review and pay for a cart |
| /orders/:id | Order details and refunds |

## References

- src/routes.ts
- /

## Coverage



The route index itself is not a test.

## Still to explore

Unlinked and permission-restricted screens may require further exploration.