Diamond Stone: documents and terms

Date: 2026-11-11. Revision 1. Screens are in docs/ui-shell-mockup.html, section "Documents and terms". Flows are in docs/system-flows.html and docs/user-flows.html.

How every paper the company issues is made, fixed, shared and proved: quotes, proformas, tax invoices, credit notes, packing lists, delivery notes, statements, export papers, payslips and letters. And how the terms and conditions behind them are kept, attached and accepted.

This is a plan, not legal or tax advice. Section 12 lists what a lawyer and the tax adviser must confirm. Points marked (unverified) came from secondary sources or common practice and were not read in the law itself. The wording of the terms is the lawyer's to write; this plan only says which clauses a stone trader normally needs.

1. Five rules

1. A document is made from the record, never typed. The customer, the stone, the quantities and the amounts come from the order. Nobody edits a PDF.
2. Once issued, it never changes. The file is stored once with a fingerprint. A correction is a new document: a new version of a quote, or a credit note against an invoice. The old one stays, marked "Replaced" or "Cancelled".
3. Terms are versions. Every document records which version of which terms applied on the day. Changing the terms never changes a document already issued.
4. Terms are shown before the agreement, not after. They go on the quote and the proforma, and the customer's acceptance is recorded. Terms that first appear on the invoice are too late to bind anyone (unverified; general contract principle).
5. Everything the customer receives can be checked. Each document carries a code that opens a page saying whether it is genuine and still in force.

2. The documents

Drafts have no number. A number is given at the moment of issue, inside the same database write, so each series has no gaps. A cancelled document keeps its number and is marked; nothing is deleted.

3. What a tax invoice must carry

From the VAT Executive Regulations, as summarised by Deloitte. The article numbers differ between secondary sources and are to be confirmed with the tax adviser.

• The words "Tax Invoice".
• Issue date, date of supply, and the payment date if an advance came first.
• A serial number.
• Our name, address and VAT number.
• The customer's name, address and VAT number if they have one.
• Description and quantity of the goods.
• Amount before VAT, the rate, any discount, the taxable value and the VAT due.

Rules the system enforces around it:

Also printed, by custom rather than tax law: commercial registration number, the amount in words in both languages, the bank details, and the verification code.

4. Ready for e-invoicing (Fawtara)

Oman is introducing electronic invoicing through accredited providers on the Peppol network. The format is published (PINT-OM, on UBL 2.1). A decision of August 2026 is reported to set 1 October 2027 for businesses at or below OMR 5 million a year and 1 April 2027 above it. That date came from one secondary source; the gazette text was not read. Plan for 1 October 2027 and confirm.

After that date the electronic record is the invoice between businesses, and the PDF is a courtesy copy. So the data must be right from the first day, long before 2027:

The join to the provider is one adapter behind the outbox. The archive copy is a PDF that can carry the electronic record inside it, so one file holds both.

5. Export papers

Generated from one shipment record, so the buyer's name, the description, the quantities and the weights cannot differ between papers. Banks refuse most letter of credit presentations the first time, and conflicting details between documents is the leading reason (ICC Academy).

Letter of credit mode. When an order is under a letter of credit, the description and the parties' names are locked to the credit's exact wording, the presentation deadline is a timer, and a paper with an error is reissued, never altered.

Origin. Stone bought abroad and re-exported is not of Omani origin. The country of origin comes from the supplier order, not from our address.

6. Terms and conditions

The sets

Which terms go on which paper is a rule, not a choice made each time. The rule reads the kind of document, whether the customer is a business or a person, and whether they are in Oman. Sales cannot remove terms from a quote. A customer with their own agreed terms has them recorded on their account, approved by the owner, and the rule then uses those.

What the default terms of sale cover

A list of clauses for the lawyer, drawn from published terms of stone suppliers (Brachot; Stone Wholesalers; others seen in summary). Each is a switch with wording in both languages. The figures are settings.

The terms for individuals drop or soften 6, 11, 13 and 15, as consumer law requires.

How terms are kept

• Each set has versions. A version has English and Arabic side by side, a date it comes into force, and a list of what changed.
• A new version is drafted by the administrator, approved by the owner, and only then used. It applies to documents issued from its date; earlier documents keep theirs.
• A language model may draft the Arabic from the English. A person who reads Arabic approves it, and the lawyer says which language governs if they differ.
• Each version is itself a fixed PDF with a fingerprint, so "the terms you accepted" can always be produced exactly.

7. Proving that someone agreed

The key three terms are shown in plain words on the acceptance screen (matching: one lot, within the range approved; claims; payment) with the full text one tap away. Nothing is pre-ticked.

Oman's Electronic Transactions Law (Royal Decree 39/2025) recognises electronic documents and signatures. Its detailed conditions could not be read. A recorded acceptance backed by a one-time code or passkey is normally enough for ordinary sales (unverified). Banks, certificates of origin, attested invoices and tenders still expect ink and a stamp, so every document has a print, sign and stamp version, and the signed scan is stored against the original.

8. Making the file

Arabic is the main risk. Typst's own documentation warns that right-to-left output may have faults. So: a set of reference documents in Arabic and in mixed Arabic and English is checked on every change (letter joining, numbers and codes inside Arabic lines, mirrored columns, text that can be searched and copied). Amounts and codes always use Western digits. If Typst fails this in Stage 0, the fallback is a different engine behind the same module; nothing else changes.

Templates are versions too: letterhead, footer, which optional parts show (amount in words, stamp and signature, verification code), column choices. A new template version is tested against sample records and approved before use.

9. Sharing

One Share sheet on every document, the same everywhere.

Rules:

• Payslips and statements never go as open links. Sign-in is always required.
• A link's preview in a chat shows only "Document from Diamond Stone": never a name or an amount.
• A link to a replaced or cancelled document says so, and offers the current one.
• Every send is recorded on the document: who, to whom, by which way, when. "Opened" is recorded for portal and link views only, shown as a guide and never as proof; automatic previews are not counted. The privacy notice says this is recorded.
• A send is never repeated by accident: each has a one-time key in the outbox.
• Staff see the same file the customer gets, through "See what they will see".

10. Checking a document, and bank-detail fraud

The code. Every document carries a square code and a short address. Scanning it opens a public page that shows only: the kind of document, its number, its date, and whether it is genuine and in force, replaced or cancelled. Amounts, names and the file itself need sign-in.

Bank details. Invoice fraud usually works by sending a copy of a real invoice with a changed account number. So:

• The company's bank details live in one record. A change needs a second person and a waiting period, and tells the owner.
• Every invoice prints: "We never change our bank details by email or WhatsApp. Check by phone before paying a new account."
• After sign-in, the verification page shows the bank details, so a customer can compare them with the paper in their hand.
• The same control already applies to suppliers' bank details (docs/ACCOUNTS.md).

Stamp and signature. Images of the stamp and of a signature are placed only by the roles allowed, and each use is recorded. An image of a stamp is not an electronic signature; a company seal from a licensed provider can be added later if the lawyer advises it.

11. Settings

Under Control → Documents. Every one has a default, and a change is recorded.

12. For the lawyer and the tax adviser

1. The wording of every clause in section 6, in both languages, and which language governs.
2. Whether the limit of liability and the "no claims after fixing" clause would stand, given the court's power over unfair standard terms.
3. The separate terms for individuals under the Consumer Protection Law.
4. The current cap on late-payment interest, and whether to charge it at all.
5. Whether a recorded acceptance with a one-time code or passkey is sufficient under Royal Decree 39/2025, and when a licensed signature is needed.
6. The exact tax-invoice article and contents; the 15-day rule; the wording for export and reverse-charge sales; advance invoices.
7. The exchange-rate source for invoices not in rials.
8. The e-invoicing date that applies to this company, and the accredited provider.
9. Whether the registration number must appear on stationery.
10. Whether recording that a link was opened needs anything beyond the privacy notice.
11. Retention periods for each kind of document, including payslips and letters.

13. Decisions for the owner

1. Claims window: 7 days proposed.
2. Whether to charge for storage after the agreed date.
3. Whether a late-payment charge is wanted at all.
4. Whether quotes may be sent as open links to people with no account (proposed: yes, ending after 30 days).
5. Whether the stamp and signature appear on documents by default.
6. Documents in both languages for everyone, or Arabic only on request.

14. Screens

Drawn in the mockup: a final document; the Share sheet; every paper of one order; terms with versions and rules; one set of terms; a document layout; the public verification page; the customer accepting the terms. Still to draw: the comparison between two versions of terms; a credit note being raised; the export set for one shipment with its letter of credit check; the bank-details change with its second person. They are listed in docs/INVENTORY.md.

15. Sources

Read directly: Deloitte on the VAT Executive Regulations; the Peppol PINT-OM rules; decree.om and Legal500 on Royal Decree 39/2025; the Curtis Oman law blog on interest; Oman Observer on unfair standard terms; ICC Academy on letter of credit refusals; the published terms of Brachot and Stone Wholesalers; Typst's documentation; Meta's documentation for document messages; MDN and caniuse on Web Share. From summaries only (unverified): the e-invoicing dates and field counts; the 15-day rule; the currency and language rules; consumer-law periods; other suppliers' terms. The Arabic texts of the regulations and decisions were not read.

Currencies on documents (added 11 November 2026)

A document is in the currency of its record. The amount in words, the bank details (the account for that currency, with SWIFT code and IBAN) and, where VAT applies, the rial value of the tax with the rate used all follow automatically. The default terms of sale state that bank charges are the buyer's. See docs/CURRENCY.md.

Stone names on documents (added 11 November 2026)

Every document shows a stone as name, kind of rock, colour and origin, with the variant's code and customs code from the catalogue. The supplier's name for a stone appears only on purchase orders to that supplier. A customer's own name for a stone is printed on their papers with our item code, not beside our catalogue name (docs/CATALOGUE.md, "Revision 2").

Matching in the terms and papers (added 11 November 2026)

Clauses 1, 2 and 4 of the default terms are replaced by the set in docs/MATCHING.md section 10: a commitment to one lot within the approved range, how it is judged, what approval means, and the position on spare and later lots. New papers: the range approval and the layout plan (numbered pieces by crate), both kept against the order and carried in the portal. Crate labels carry our code and the piece numbers. No paper offers or describes blocks; the customs code for blocks is not used.

Shipping papers (added 12 November 2026)

Section 5 listed three export papers. The full set by route (Oman, collection, Gulf road, sea) is in docs/LOGISTICS.md sections 7 and 8: order confirmation, delivery note with the layout plan, collection authority, Oman's electronic transport document, export declaration kept as proof of export, bill of lading and its release, container weight, insurance, wood treatment, conformity, letter of credit papers. Section 9 there sets which papers can show Diamond Stone alone and which may reveal the factory. The packing list carries thickness in mm on every line.

Controls added (12 November 2026)

From docs/CRITIQUE.md section 6: the code on a paper is a random token, never the paper's number, and checking is rate-limited; one printed web address, locked at the registrar; an order's terms, settings and rate are fixed at acceptance for every later paper; a customer's papers are made from a customer view of the record that holds no supplier fields, and their file names and embedded data are checked for them; masking never blanks a field the law requires. Papers read "Omani Beige (our ref. SB-01), limestone, Oman". The amount in words is on by default.