I have to admit, this is something that I haven’t given a lot of thought, having had it in the back of my head that it would be a remote possibility in the distant future. 
At the same time, providing what is essentially an API to a complex application is pretty significant task. You want to strike a balance between abstraction and detail.
Take a look at OmniOutliner Pro’s dictionary. That is a classy (though a bit exhaustive!) example of how AppleScript should be supported. Not everything is directly translateable, but there are some good ideas in it, I think. Afterall, this is the dictionary that allowed Ethan to take an ordinary outliner and turn it into an automated cross-referenced to-do list with iCal synchronisation.
Some obvious things would be full access to the Binder. Allow the creation, movement, and deletion of items within it. This would probably be most easily accomplished by allowing the scripter to assign item objects to variables, and a battery of methods which allow a full range of horizontal and vertical movement, adding, and trashing. This would probably be best done by providing the ability to assign binder objects to variables, and using them as targets in the move commands, basically what the Move To menu currently allows. I wonder if relative up/down/left/right movement would be handy for some people, too?
Addressing objects in the Binder is something that would need a little thought. Since items can have identical names, access to the underlying reference number would be important. Fixed items such as the Draft should probably be accessible by name.
Another area that could be addressed is aspects and settings of the project itself. You probably would not want to go too far into that–but I can see how the setting of some things would be nice to add. For example, the ability to hold label/status in an array. Editing them would probably be unnecessary, more important is allowing the script to “know” what meta-data exists in the document, for the purposes of assigning them to binder objects. Of course there is the project notes, references and scratchpad. The contents of these should definitely be accessible, perhaps not the functions of them. For example, there is little reason to script Scratch Pad’s handy data movement feature, since a script can just as easily do that itself.
In the Document object. One would definitely want access to the two rich text areas: Main edit and Notes (see next paragraph for details). Synopsis, Title, and other meta-data. A good question would be how to address label/status, since each project can supply its own nomenclature. The simple answer would be simply to call them label/status, but that is merely the default nomenclature. Perhaps referring to them as their Corkboard appearance refers to them: pins and stamps? Keywords are pretty straight-forward. That is just an array. References are a little more interesting, but a reference object with a name and URL would be pretty easy to interface with, I think, but a better question would be whether or not there would be much third-party need to mess with reference lists. I suppose it could be handy if you have a list of URLs and wanted to turn them into references.
In the text itself; have a look at OmniOutliner’s dictionary in the Extended Text Suite section; lots of useful methods in there. Footnote/annotation toggle on ranges, and the ability to linkTo binderItem, and unlink on a range of text. Scripted link manipulation could be very useful. Annotation and footnote access would be more important in the import/export type scripts. This could potentially expand Scrivener’s ability to interface with odd applications. For example, getting Page’s comments and annotating them correctly, or vice versa. Access to highlights would let a person go through the entire project, highlighting a certain phrase they know from experience they tend to abuse.
Splits would need to be addressed. There needs to be a keyword to operate on the focussed split, as well as the unfocussed split. The ability to test if the editor is currently split or not. Either that or ‘smart’ handling:
set edit_me to rich text from selected split
Would just get text from the editor if no splits are open, as would from unselected split.
Maria, your suggestions are more along the lines of implementation than syntax and access: Here are some possible methods and their requirements.
This should be a fairly easy script to write if you have access to the rich text and rudimentary Binder manipulation. You wouldn’t need access to the cut command per say, as you can find spots in a text string, split the string, and create a new document with string2. The ability to create a new document with a rich text block in place–would that bypass Scrivener’s auto-Synopsis?
This would need the ability to grab the binder items currently represented in the E.S. session; and it would also require access to the focussed split, as well as the export settings (which may be overkill for round 1).
I’m not sure what you mean with this one. Do you mean the ability to create named snapshots? That is actually an interesting idea. You could create ‘machine friendly’ titles that saved the meta-data. It is prone to failure though, unless you are pretty careful about keeping labels/status around even after nothing current is using them. What is the length limitation on snapshot titles? Making snapshots in general is probably not a bad idea, actually. It would make running a script much safer if you knew it would back up the current text before slicing and dicing.
Anyway. I am not a super-experienced AppleScript coder. I know enough to create some simple automation or edit things that others have done. This will all benefit me in the end though, through the OSA. This all would put Scrivener out on (yet another) platform of its own. There are very few authoring programs with good AppleScript support.
