Update README, add screenshots

README.md

@@ -32,9 +32,63 @@ Example useful things you can do with this approach:
 - send urgent actions to those most likely to respond urgently.
 - follow up cancelled regulars to see if they can be rescued.
 
+## Features:
+
+Some of the screenshots use numeric codes for the category labels, but these could be your own labels (e.g. Amazing, Loyal...) if your organisation does not want to use the codes.
+
+### Search » Contacts By Category
+
+![Screenshot shows a page titled Contacts by Category. There's a selector for the Category, an Action button and a table listing contact name, type, category, email](./images/screenshot-search-contacts-by-category.png)
+
+This search form gives a quick way to select contacts in one or more categories either to browse, or to do bulk operations like starting a mailing.
+
+### Dashlet / Reports » Contact Category Counts
+
+![Screenshot shows title: Contact Category Counts. Shows a list of all categories and how many contacts are in each one. A table has two columns, Category and Count. A few sample rows are listed.](./images/screenshot-reports-contact-cat-counts.png)
+
+This report/dashlet gives you a top-level overview of your categories. The category icon/names are links that take you through to the Contacts by Category search page for that category.
+
+### Reports » Contact Category Flows
+
+![Screenshot shows: Category Flows title. There's a start and end date field and a checkbox for "Show changes only" and a button named Calculate flows. There's a Sankey diagram which shows how many contacts moved between which categories between the two selected dates.]
+
+This report allows you to inspect flows of contacts between categories between two given dates. Leaving the end date blank means use the current category.
+
+There's a **Show changes only** checkbox. This may be useful to focus in on only the contacts who have changed category; e.g. if between two dates 1000 contacts have not changed category then it can be hard to see that 20 have changed when the diagram has to represent 1020 contacts.
+
+### Contacts » Categories set-up/configuration screen
+
+![screenshot: Contact Category Settings. Each contact is assigned the first category that matches, using the assignment order. When categories are listed, the presentation order is used. There are radio-button controls to switch between assignment and presentation order. Below are listed the categories in the selected order. There's a button to copy the order from the other order. Each category listed has an icon, a colour, a label and a description. They also have buttons: Edit, Delete, Move. A few sample categories are shown for things like: Multiple time major donors; Major donor: new; Regular donor: active etc.](./images/screenshot-config-main.png)
+
+This screen is where you define your categories, based on your SearchKit searches and/or groups.
+
+_Assignment order_ shows the categories in the order in which they will be evaluated per contact. If the first category matches for a contact, that is assigned. If not, the 2nd category is tested and assigned if possible etc.
+
+_Presentation order_ is purely cosmetic and has no baring on who gets what category. It's common for this to be the same as Assignment order, but there are times when you might want to present the list in a different order, e.g. if you wanted to identify all contacts without marketing consent first it might make the searches for the more interesting categories simpler and easier to manage, but when presenting them, this group is of less interest/value and you want to see it last.
+
+Editing each category looks like this:
+
+![Screenshot shows form called Contact Category Settings. Fields are: Category label, Color, Icon, Description (example is: Multiple time major donors.), How are contacts identified (example shows SearchKit search), SearchKit Search (example has "ContactCategories Locus 3.5" selected). There's buttons for Cancel and Done.](./images/screenshot-config-search-kit-cat.png)
+
+- The category label is the primary way the category is shown in most places.
+  Keep it short. You might use codes like 3.x for major, 2.x for regular, 1.x for occasional donors; or words like Amazing, Loyal, Drifting...
+- Colour and icon: the icon is used commonly; colour a bit less so due to SearchKit limitations.
+- Description: explain in human terms what this does.
+- How are contacts identified? one of:
+  - Search Kit search
+  - Group
+  - There's also a special 'default' one required, but you can't select that.
+    It's used for the default category that gets applied if none of the others match.
+
+### Scheduled job: ContactCategory.sync
+
+This job should be configured to run hourly, but it will only actually make a change daily after 3am (server timezone).
+
+You could set it to run daily, but CiviCRM does not give you a choice of _when_ it runs daily, and it is better that it runs outside of working hours so the catgories stay stable during the day when they might be being queried.
+
 ## Getting Started
 
-Once installed, you'll find a (bit crude at the mo) Contact » Categories page that lets you specify your prioritised SearchKit searches to identify your contacts. A scheduled job needs to run to do the categorisation, so wait a day for that or run it manually.
+Once installed, you'll find a Contact » Categories page that lets you specify your prioritised SearchKit searches to identify your contacts. A scheduled job needs to run to do the categorisation, so wait a day for that or run it manually.
 
 You can also use SearchKit/FormBuilder to summarise people by categories, e.g. counts.